xntpd(1M)

Configuration File Options

xntpd's configuration file is relatively free format. Comments, which may be freely inserted, begin with a # character and extend to the end of the line. Blank lines are ignored. Configuration statements include an initial keyword followed by white space separated arguments, some of which may be optional. Configuration statements may not be continued over multiple lines. Arguments may be network numbers (which must be written in numeric, dotted-quad form), integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by [] in the following descriptions, while alternatives are separated by |.

peer host_address [ key # ] [ version # ] [ minpoll interval ] [ prefer ]

server host_address [ key # ] [ version # ] [ minpoll interval ] [ prefer ]

broadcast host_address [ key # ] [ version # ] [ minpoll interval ]

These three statements specify various time servers to be used and/or time services to be provided. The peer statement specifies that the given host is to be polled in symmetric active mode, i.e. that the host is requested to provide time to which you might synchronize and, in addition, indicates that you are willing to have the remote host synchronize to your time. The server statement specifies that the given host is to be polled in client mode, i.e. that the host is requested to provide time to which you might synchronize but that you are unwilling to have the remote host synchronize to your own time. The broadcast statement requests your local daemon to transmit broadcast NTP to the specified address. The latter is usually the broadcast address on [one of] your local network[s].

precision #

Indicates the precision of local timekeeping. The value is an integer which is approximately the base 2 logarithm of the local timekeeping precision in seconds. By default this value is set to -6.

The precision declared by an implementation can affect several aspects of server operation, and can be used as a tuning parameter for your synchronization subnet. It should probably not be changed from the default value, however, unless there is a good reason to do so.

driftfile filename

Specifies the name of the file used to record the ``drift'' (or frequency error) value xntpd has computed. If the file exists on startup, it is read and the value used to initialize xntpd's internal value of the frequency error. The file is then updated once every hour by replacing the old file with a new one containing the current value of the frequency error. Note that the file is updated by first writing the current drift value into a temporary file and then using rename(2) to replace the old version. This implies that xntpd must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should probably be avoided.

broadcastclient yes|no

This indicates whether the local server should listen for, and attempt to synchronize to, broadcast NTP. The default is no.

broadcastdelay seconds

Specifies the default round trip delay to the host whose broadcasts are being synchronized to. The value is specified in seconds and is typically (for ethernet) a number between 0.007 and 0.015 seconds. This initial estimate may be improved by polling each server to determine a more accurate value. Defaults to 0.008 seconds.

authenticate yes|no

Indicates whether the local server should operate in authenticate mode or not. If yes, only peers which include an authentication field encrypted with one of our trusted keys (see below) will be considered as candidates for synchronizing to. The default is no.

authdelay seconds

Indicates the amount of time it takes to encrypt an NTP authentication field on the local computer. This value is used to correct transmit timestamps when the authentication is used on outgoing packets. The value usually lies somewhere in the range 0.0001 seconds to 0.003 seconds, though it is very dependent on the CPU speed of the host computer.

keys filename

Specifies the name of a file which contains the encryption keys which are to be used by xntpd. The format of this file is described below.

trustedkey # [ # ... ]

Allows the specification of the encryption key numbers which are trusted for the purposes of determining peers suitable for time synchronization, when authentication is enabled. Only peers using one of these keys for encryption of the authentication field, and whose authenticity can be verified by successful decryption, will be considered as synchronization candidates. The arguments are 32 bit unsigned integers. Note, however, that NTP key 0 is fixed and globally known. If meaningful authentication is to be performed the 0 key should not be trusted.

controlkey #

Certain changes can be made to the xntpd server via mode 6 control messages, in particular the setting of leap second indications in a server with a radio clock. The controlkey statement specifies an encryption key number to be used for authenticating such messages. Omitting this statement will cause control messages which would change the state of the server to be ignored.

restrict address [ mask numeric_mask ] [ flag ] [ ... ]

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 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 as a dotted-quad address, the text string default, with no mask option, may be used to indicate the default entry.

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 categories, 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:

Default restriction list entries, with the flags ignore, 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).

The restriction facility was added to allow the current access policies of the time servers running on the NSFnet backbone to be implemented with xntpd as well. While this facility may be otherwise useful for keeping unwanted or broken remote time servers from affecting your own, it should not be considered an alternative to the standard NTP authentication facility. Source address based restrictions are easily circumvented by a determined cracker.

statsdir /directory/[ prefix ]

Indicates the full path of a directory where statistics files should be created (see below). This optional prefix allows the modification of the filename prefix of the file generation sets used for handling statistics logs (see filegen and statistics statement below).

statistics names

Enables writing of statistics records. names can be one or more statistics names separated by space. Currently two kinds of statistics are supported:

Statistic files are managed using file generation sets (see filegen below). The information obtained by enabling statistics recording allows analysis of temporal properties of a xntpd server. It is usually only useful to primary servers or maybe main campus servers.

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

Configures setting of generation file set name. 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. 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.

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.

Primary Clock Support

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.

For the purposes of configuration, xntpd treats reference clocks in a manner analogous to normal NTP peers as much as possible. Reference clocks are referred to by address, much as a normal peer is, though an invalid IP address is used to distinguish them from normal peers. Reference clock addresses are of the form 127.127.t.u where t is an integer denoting the clock type and u indicates the type-specific unit number. Reference clocks are normally enabled by configuring the clock as a server using a server statement in the configuration file which references the clock's address. Clock addresses may generally be used anywhere else in the configuration file a normal IP address can be used, for example in restrict statements.

There is one additional configuration statement which becomes valid when reference clock support is used. The format is:

fudge 127.127.t.u [ time1 secs ] [ time2 secs ] [ value1 int ] [ value2 int ] [ flag1 0|1 ] [ flag2 0|1 ]

There are two times (whose values are specified in fixed point seconds), two integral values and two binary flags available for customizing the operation of a clock. The configuration and interpretation of these values, and whether they are used at all, is a function of the needs of the particular clock driver.

xntpd on HP-UX currently supports the Spectracom's Netclock/2 plus a special pseudo-clock which synchronizes to the local system clock and can be used for backup or when no other clock source is available. The clock drivers, and the addresses used to configure them, are described as the followings:

127.127.1.u - Local synchronization clock driver

This driver doesn't support an actual clock, but rather allows the server to synchronize to its own clock, in essence to free run without its stratum increasing to infinity. This can be used to run an isolated NTP synchronization network where no standard time source is available, by allowing a free running clock to appear as if it has external synchronization to other servers. By running the local clock at an elevated stratum it can also be used to prevent a server's stratum from rising above a fixed value, this allowing a synchronization subnet to synchronize to a single local server for periods when connectivity to the primary servers is lost.

The unit number of the clock (the least significant octet in the address) must lie in the range 0 through 15 inclusive and is used as the stratum the local clock will run at. Note that the server, when synchronized to the local clock, will advertise a stratum one greater than the clock peer's stratum. More than one local clock may be configured (indeed all 16 units may be active at once), though this hardly seems useful.

The local clock driver uses only the time1 parameter of the fudge statement. This parameter actually provides read and write access to the local clock drift compensation register. This value, which actually provides a fine resolution speed adjustment for the local clock, is settable but will remain unchanged from any set value when the clock is free running without external synchronization. The fudge time1 parameter thus provides a way to manually adjust the speed of the clock to maintain reasonable synchronization with, say, a voice time announcement.

127.127.4.u

This driver provides an interface to the Spectracom Netclock/2 WWVB Synchronized Clocks in either Format-0 or Format-2 mode of operation at 9600 bps. When the clock is set to Format-0, the time zone switch on the clock should be set to 0 ( UTC time). When the clock is set to Format-2, the time zone switch can be set to the zone which reflects the local time.

A device file /dev/wwvb%d needs to be created, where %d is the unit number u. The valid unit number lies in the range 0 through 4 inclusive. The driver opens the RS232 output on the /dev/wwvb%d device file. This driver does not require a 1-pulse-per-second (pps) signal and automatically compensates for the baud rate on the serial port. It does not require the clock discipline or STREAMs modules.

Fudge statement is used as a general calibration factor for Netclock2. A positive time1 value will advance the time and a negative time1 value will retard the time. The parameter defaults to zero, which should be appropriate if the clock's propagation delay switches have been set appropriately. The value1 parameter can be used to set the stratum at which the peer operates. The default is 0, which is correct if you want the clock to be considered for synchronization whenever it is operating.