xntpd(1M)

DESCRIPTION

xntpd is an operating system daemon which sets and maintains the system time-of-day in synchronism with Internet standard time servers. xntpd is a complete implementation of the Network Time Protocol (NTP) version 3, as defined by RFC-1305, but also retains compatibility with version 1 and 2 servers as defined by RFC-1059 and RFC-1119, respectively.

xntpd does all computations in 64-bit fixed point arithmetic and requires no floating point support. While the ultimate precision of this design, about 232 picoseconds, is not achievable with ordinary workstations and networks of today, it may be required with future nanosecond CPU clocks and gigabit LANs.

The daemon can operate in any of several modes, including symmetric active/passive, client/server and broadcast, as described in RFC-1305. The daemon can also operate in a multicast mode in which it listens on a reserved multicast address. A broadcast/multicast client can discover remote servers, compute server-client propagation delay correction factors and configure itself automatically. This makes it possible to deploy a group of workstations without specifying configuration details specific to the local environment.

Ordinarily, xntpd reads the /etc/ntp.conf configuration file at startup time in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited, configuration entirely on the command line, obviating the need for a configuration file. This may be particularly appropriate when the local host is to be configured as a broadcast or multicast client, with all peers being determined by listening to broadcasts at run time. Various internal xntpd variables can be displayed and configuration options altered while the daemon is running using the ntpq and xntpdc utility programs.

COMMAND LINE OPTIONS

THE CONFIGURATION FILE

The xntpd configuration file is read at initial startup in order to specify the synchronization sources, modes and other related information. Usually, it is installed in the /etc/ntp.conf directory, but could be installed elsewhere (see the -c conffile command line option).

The file format is similar to other UNIX configuration files. Comments 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, some of which may be optional, separated by white space. 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 |. The notation [ ... ] means an optional, indefinite repetition of the last item before the [ ... ].

While there is a rich set of options available, the only required option is one or more server, peer or broadcast commands described in the "Configuration Options" section. The examples in /etc/ntp.conf.example may also be helpful.

CONFIGURATION OPTIONS

The configuration commands are as described below:

peer address [ key key_id ] [ version version_id ] [ prefer ]

server address [ key key_id ] [ version version_id ] [ prefer ] [ mode mode ]

broadcast address [ key key_id ] [ version version_id ] [ ttl ttl ]

The above three commands can be used to specify either the name or address of the time server and the mode in which the time server should operate. The address can be either a DNS name or an IP address in dotted-quad notation.

The peer command specifies that the local server is to operate in symmetric active mode with the remote server. 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 may be the better source of time.

The server command specifies that the local server is to operate in client mode with the specified remote server. 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 is the most common operating mode (by far).

The broadcast 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/multicast address specified. Ordinarily, this specification applies only to the local server operating as a sender; for operation as a broadcast client, see the broadcastclient or multicastclient commands below. In this mode, address is usually the broadcast address of (one of) the local network(s) or a multicast address assigned to NTP. The address of 224.0.1.1 is assigned to NTP. This is presently the only address that should be used. Note that the use of multicast features requires a multicast kernel.

OPTIONS

Authentication Key File Format

The NTP standard specifies an extension allowing verification of the authenticity of received NTP packets, and to provide an indication of authenticity in outgoing packets. This is implemented in xntpd using the DES encryption algorithm. The specification allows any one of a possible 4 billion keys, numbered with 32 bit unsigned integers, to be used to authenticate an association. The servers involved in an association must agree on the value of the key used to authenticate their data, though they must each learn the key independently. The keys are standard 56 bit DES keys.

Additionally, another authentication algorithm is available which uses an MD5 message digest to compute an authenticator. The length of the key or password is limited to 8 characters. xntpd reads its keys from a file specified using the -k command line option or the keys statement in the configuration file. While key number 0 is fixed by the NTP standard (as 56 zero bits) and may not be changed, one or more of the keys numbered 1 through 15 may be arbitrarily set in the keys file.

The key file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form

where keyno is a positive integer, type is a single character which defines the format the key is given in, and key is the key itself.

The key may be given in one of four different formats, controlled by the type character. The four key types, and corresponding formats, are listed following.

FILEGEN UTILITY

filegen name [ file filename ] [ type typename ] [ link|nolink ] [ enable|disable ]

This command helps in configuring the generation-file set name. The generation-file sets provides a mean for handling files that are continuously growing during the lifetime of a server. Server statistics are a typical example for such files. The 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 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. (Most important: they can be removed to free space for new data produced.) Filenames of set members are built from three elements. name is name of the statistic to be collected. Currently only two kinds of statistics are supported: loopstats and peerstats.

REFERENCE CLOCK DRIVERS

Individual clocks can be activated by configuration file commands, specifically the server and fudge commands described in the xntpdc(1M) manual page. The following discussion presents information on how to select and configure the device drivers in a running UNIX system.

Radio and modem 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/deviceu to the particular hardware device involved, where u correspond to the unit number above.

Following is a list showing the type and title of each driver currently implemented. The compile-time identifier for each is shown in parentheses.

The following four clock drivers are supported by HP.

The clock drivers mentioned below are not supported by HP. They may work, but have not been tested. They are provided as is, for the convenience of the diverse users.

All TrueTime receivers are now supported by one driver, type 5. Types 11, 15 and 25 will be retained only for a limited time and may be reassigned in future.

DEBUGGING HINTS FOR REFERENCE CLOCK DRIVERS

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 xntpdc(1M) manual 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 many of the problems occurring during installation are due to problems such as miswired connectors or improperly configured device links at this stage.

If RS232 messages are getting to and from the clock, variables can be inspected using the ntpq command (see ntpq(1M)). First, use the pe and as commands to display 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 association ID 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 file and the commands in xntpdc (see xntpdc(1M)).

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 clock. This file is managed by the filegen facility described above and requires specific commands in the configuration file. This forms a highly useful record to discover anomalies during regular operation of the clock.

SLEW

SLEW is not recommended by HP because it reduces accuracy and stability.

The NTP daemon has three regimes in which it operates:

The catch is that the dispersion on a WAN is frequently much greater than 128 milliseconds, so you may see (a lot of) the STEP changes, perhaps as large as 1000 milliseconds (depends on your network). But there are customer applications that are quite allergic to the STEP changes, particularly backward steps (which will happen about half the time). Databases and financial transaction systems are examples.

The good news is that NTP can be forced to never make a STEP, but instead SLEW the clock to drive the offset to zero. This is accomplished with the -x option on the command line. This effectively removes the middle operating regime. You won't get millisecond (or microsecond) precision with this method, but you probably can't get that over a WAN anyway.

It is important to note that SLEWING is a cover-up for a more fundamental problem (poor connection to the timesource), and it does not solve this problem. SLEWING is not recommended by HP because it causes reduced accuracy and stability, and it leads to anomalous behavior that can be quite confusing. For example, you will see messages similar to this in the syslog:

But this does not mean that your system clock has been stepped. Only the NTP daemon process has seen a step in its notion of the current time (and this will be passed on to clients). The system time is being gradually adjusted in a series of SLEW maneuvers, and the SLEW rate is quite limited. Be warned that it can take a long time for the system clock to reach nominal correctness, and much longer to stabilize. Each cpu model is unique, but the maximum slew rate is typically about 40 milliseconds per second. Thus a SLEW adjustment of 411 seconds will take over 10,000 seconds (about 3 hours) to complete. A better approach would be to run the ntpdate command once at system startup, and accept the one STEP change that comes with it. Then start the NTP daemon process xntpd and it will never make a STEP as long as your connection to the timesource is good. This method also overcomes the 1000 seconds problem. The NTP startup script /sbin/rc2.d/S660xntpd will do this automatically if you configure the NTPDATE_SERVER variable in /etc/rc.config.d/netdamons. A properly configured NTP hierarchy with average networking (say 10Base-T) can run for years without ever making a STEP change.

AUTHOR

xntpd was developed by Dennis Ferguson at the University of Toronto.

Text amended by David Mills at the University of Delaware.

FILES

SEE ALSO

ntpq(1M), ntpdate(1M), xntpdc(1M).