ntp.conf - Network Time Protocol (NTP) configuration file
The xntpd configuration file, /etc/ntp.conf, is read by xntpd at startup.
The xntpd configuration file is relatively free of formatting. Comments, which may be freely inserted, begin with a # 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, separated by white space. Configuration 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 ``'' in the following descriptions, while alternatives are separated by ``|''.
peer host_address [key #] [version #] [prefer] server host_address [key #] [version #] [prefer] [mode #] broadcast host_address [key #] [version #] [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 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. This command specifies that the local server is to operate in ``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. 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 broadcast or 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 broadcastclient or multicastclient 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 18.104.22.168 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; version 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 synchronization 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 coordinated with the network administrator(s).
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 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 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 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). 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 directory 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 correctly authenticated using a trusted key and key identifier. The default for this flag is disable (off). 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). 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 (22.214.171.124) is assumed.
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 utility. 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 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 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 specific 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 included in the configuration file, or if the keys do not match, such requests are ignored. Specifies the encryption key identifiers that are trusted for the purposes of authenticating peers suitable for synchronization. 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.
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 after 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 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 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 entry in the list. Note that, while address is normally given in dotted-quad format, the text string default, with no mask option, may be used to indicate the default entry.
filegen name [file filename] [type typename] [flag flagval] [link | nolink] [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 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, 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 previously. 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 filesystem hierarchy denoted by prefix. This part reflects individual elements of a file set. It is generated according to the type of a file set.
Specifies the default delay to be used in cases where the delay calibration 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.
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 variables. The leap warning bits that can be set in the leapwarning variable (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).
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 device 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:
|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|
Reference clocks are configured using a server statement in the configuration file. Typically, this is the only command necessary to configure a reference clock. The following is the format for this command: server 127.127.t.u [prefer] [mode m]
In the preceding command: Specifies the clock type number. Specifies the unit number. This is typically 1, but can range from 0-3. Modifies 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 follow 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 assigned by xntpd. Specifies a four-character, null-terminated ASCII string, if you want to override the default reference identifier assigned 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 described 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 discipline source. This is useful if you want to use NTP in an isolated environment with no radio clock or NIST modem available. Choose a machine that has a good clock oscillator and configure it with this support. 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 discipline 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 Synchronization 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 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 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 ignored. This behavior is intended for use when an external discipline source controls the system clock.
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 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. 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.
127.127.4.u - 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 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 synchronization; 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 (?) indicates 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 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.
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 retrieves this table and writes it to the clockstats file when the first timecode message of a new day is received.
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 designed 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, 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 do not. This driver tries to do the best it can with what it gets. Initial 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 (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 (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.
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 the following ways: In manual mode, a call is initiated by setting fudge flag1 using xntpdc, either 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 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 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). Denotes modem calibration (see driver listing). Denotes an on-time character.
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 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 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 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 is used only in automatic mode when primary time is to be obtained through ACTS, and backup NTP peers used only when ACTS fails.
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 using 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 others 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 assumes 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 configured for 9600-baud operation.
Default name of the configuration file Conventional name of the drift file Conventional name of the key file
Commands: ntp(1), ntpdate(8), ntpq(8), xntpd(8), xntpdc(8)
Network Administration delim off