XNTPD(8)

NAME
xntpd | Network Time Protocol daemon

SYNOPSIS
xntpd [ |ab ] [ |c conffile ] [ |e authdelay ] [ |f driftfile ] [ |k keyfile ] [ |l loopfile ] [ |p pidfile ] [ |r broaddelay ] [ |s statsdir ] [ |t trustedkey ]

DESCRIPTION
Xntpd is a daemon which maintains a Unix system's time|of|day in agreement with Internet standard time servers. Xntpd is a complete implementation of the Network Time Protocol (NTP) version 2 standard as defined by RFC 1119 and also retains compatability with version 1 servers as defined by RFC 1059. Xntpd does all computations in fixed point arithmetic and is entirely free of floating point code. The computations done in the protocol and clock adjustment code are carried out with high precision and with attention to the details which might introduce systematic bias into the integrations, to try to maintain an accuracy suitable for synchronizing with even the most precise external time source.

Ordinarily, xntpd reads its configuration from a file at startup time. The default configuration file is /etc/ntp.conf, though this may be overridden from the command line. It is also possible to specify a working, though limited, xntpd configuration entirely on the command line, obviating the need for a configuration file. This may be particularly appropriate when xntpd is to be configured as a broadcast 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 through use of the xntpdc(8) program.

The following command line arguments are understood by xntpd (see the configuration file description for a more complete functional description): run in "authenticate" mode listen for broadcast NTP and sync to this if available specify an alternate configuration file specify the time (in seconds) it takes to compute the NTP encryption field on this computer specify the location of the drift file specify the location of the file which contains the NTP authentication keys specify the name of the file to record loop filter statistics specify the name of the file to record the daemon's process id specify the default round trip delay (in seconds) to be used when synchronizing to broadcasts specify a directory to be used for creating statistics files add a key number to the trusted key list

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 ] [ prefer ]
server host_address [ key # ] [ version # ] [ minpoll ] [ prefer ]
broadcast host_address [ key # ] [ version # ] [ minpoll ]

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 which you might synchronize to and, in addition, indicates that you are willing to have to remote host synchronize to your time if need be. 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 which you might synchronize with 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].

The key option, when included, indicates that all packets sent to the address are to include authentication fields encrypted using the specified key number (the range of which is that of an unsigned 32 bit integer). The default is to not include an encryption field. The version option allows one to specify the version number to be used for outgoing NTP packets. Versions 1, 2, and 3 are the choices, version 3 is the default. The minpoll option specifies that the polling interval should be kept clamped at the (64 second) minimum even when the local daemon isn't using the remote server's data for synchronization. This is the default for broadcasting. Otherwise this option should not be specified other than for testing since it will increase traffic to the servers without purpose. The prefer option marks the host as a preferred host. Preferred hosts determined the validity of the PPS signal and are the primary selection for synchronisation when found in the set of suitable synchronisation sources.

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(3) 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.

monitor yes|no

Indicates whether the xntpd traffic monitoring function should be enabled or not. When enabled, this causes the origin address of each packet received by the server to be recorded along with a limited amount of additional information, such as the mode of the request and whether it originated from an NTP server port or not. Traffic monitoring data may be inspected using the xntpdc(8) monlist command. The default is "no", i.e. traffic monitoring should not be done.

Note that the traffic monitoring facility will increase the CPU used by xntpd, as well as increasing the daemon's memory utilization by as much as 8.5 kilobytes. This facility is normally useful for the detection of peers with malfunctioning software or which are sending bogus data. It is primarily intended for very popular servers which exchange time with large numbers of peers, though it may also be useful for access monitoring of local servers if you are willing to accept the overhead.

broadcastclient yes|no

This indicates whether the local server should listen for, and attempt to synchonize 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 synchonizing 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. The value is usually computed using the authspeed program included with the distribution.

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 sychonization, 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 synchonization 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.

requestkey #

Xntpd allows run time reconfiguration to be performed using the xntpdc(8) program. Such requests must be authenticated. The requestkey statement allows the specification of a 32 bit unsigned integer key number to be used for authenticating such requests. Note that if no requestkey statement is included in the configuration file the run time reconfiguration facility will be disabled.

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 encription 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 catagories, those which restrict time service and those which restrict informational queries and attempts to do run time reconfiguration of the server. One or more of the following flags may be specified: Ignore all packets from hosts which match this entry. If this flag is specified neither queries nor time server polls will be responded to. Ignore all NTP mode 6 and 7 packets (i.e. information queries and configuration requests) from the source. Time service is not affected. Ignore all NTP mode 6 and 7 packets which attempt to modify the state of the server (i.e. run time reconfiguration). Queries which return information are permitted. Decline to provide mode 6 control message trap service to matching hosts. The trap service is a subsystem of the mode 6 control message protocol which is intended for use by remote event logging programs. Declare traps set by matching hosts to be low priority. The number of traps a server can maintain is limited (the current limit is 3). Traps are usually assigned on a first come, first served basis, with later trap requestors being denied service. This flag modifies the assignment algorithm by allowing low priority traps to be overridden by later requests for normal priority traps. Ignore NTP packets whose mode is other than 6 or 7. In effect, time service is denied, though queries may still be permitted. Provide stateless time service to polling hosts, but do not allocate peer memory resources to these hosts even if they otherwise might be considered useful as future synchronization partners. Treat these hosts normally in other respects, but never use them as synchronization sources. This is actually a match algorithm modifier, rather than a restriction flag. Its presence causes the restriction entry to be matched only if the source port in the packet is the standard NTP UDP port (123). Both "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, 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.

trap host_address [ port port_number ] [ interface interface_addess ]

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 unspecified a value of 18447 is used. If the interface address is not specified the message is sent with a source address which is that of the local interface the message is sent through. Note that on a multihomed host the interface used may vary from time to time with routing changes.

The trap receiver will generally log event messages and other information from the server in a log file. While such monitor programs may also request their own trap dynamically, configuring a trap receiver will ensure that no messages are lost when the server is started.

maxskew seconds

Set the system maximum skew parameter to the number of seconds given. The default value is 0.010 seconds. This is a tuning parameter of use in improving performance when network link conditions are poor, and should probably not be changed unless your server is to run under exceptional conditions.

select algorithm_number

Selects the use of one of five selection weight algorithms. The default is algorithm number 1, which is the algorithm specified in RFC 1119. Algorithm numbers 2 through 5 select alternative, experimental selection weighting algorithms, all of which tend to give a greater degree of trust to either lower stratum and/or lower delay peers than the standard algorithm.

resolver /path/xntpres

Indicates to the daemon the full path to the xntpres program. This utility is used when names requiring resolution (rather than numeric addresses) are used in peer and server entries in the configuration file. As xntpres makes use of mode 7 runtime reconfiguration this facility must also be enabled if the procedure is to exceed (see the requestkey and keys statements above).

statsdir /directory

Indicates the full path of a directory where statistics files should be created (see below). This keyword allows the (otherwise constant) filegen filename prefix to be modified for file generation sets used for handling statistics logs (see filegen statement below).

statistics name...

Enables writing of statistics records. Currently two kinds of statistics are supported. enables recording of loop filter statistics information. Each computation of the local clock parameters 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) and time (seconds and fraction past UTC midnight). The next three fields show last offset, current drift compensation value and time constant of the loop filter.
enables recording of peer statistics information. This includes statistics records of all peers of a NTP server and of the PPS filter, if PPS signal handling is supported by the server. Each valid update appends a line of the following form to the current element of a file generation set named "peerstats":

    48773 10847.650 127.127.4.1 9714 |0.001605 0.00000 0.00142
    The first two fields show the date (modified Julian) and time (seconds and fraction past UTC midnight), while the next two fields are the peer address and status, respectively. The final three fields show offset, delay and dispersion.

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 ] [ flag flagval ] [ linknolink ] [ enabledisable ]

Configures setting of generation file set name. Generation file sets provide a means for handling files that are continously growing during the lifetime of a server. Server statistics are a typical example for such files. Generation file sets provide access to a set of files used to store the actual data. At any time at most one element of the set is being written to. The type given specifies when and how data will be directed to a new element of the set. This way, information stored in elements of a file set that are currently unused are available for administrational operations without the risc of desturbing the operation of xntpd. (Most important: they can be removed to free space for new data produced.) Filenames of set members are built from three elements. This is a constant filename path. It is not subject to modifications via 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 above. This string is directly concatenated to the prefix mentioned above (no intervening '/' (slash)). 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 is reflects individual elements of a file set. It is generated according to the type of a file set as explained below.

A file generation set is characterized by its type. The following types are supported: The file set is actually 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 members during runtime, however it provides an easy way of seperating files belonging to different xntpd server incarnations. The set member filename is built by appending a dot ('.') to concatentated "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 form <YYYYMMDD>. YYYY is a 4 digit year number (e.g. 1992). MM is a two digit month number. DD is a two digit day number. Thus, all information written at December 10th, 1992 would end up in a file named "<prefix><filename>.19921210". Any file set member contains data related to a certain week of a year. The term week is definied 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 Jamuary, 10th 1992 would end up in a file with suffix ".1992W1". 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 elment is generated per year. The filename suffix consists of a dot and a 4 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 "disabled".

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 specified, a hard link from the current file set element to a file without suffix is created. When there is already a file with this name and the number of links of this file is one, it is renamed appending a dot, the letter "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 accessed by a constant name.

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.

Addionally, a new experimental authentication algorithm is available which uses an MD5 message digest to compute an authenticator. Currently the length of the key or password is limited to 8 characters, but this will eventually be changed to accomodate an effectively unlimited password phrase. 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 keyno type key

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 three different formats, controlled by the "type" character. The three key types, and corresponding formats, are listed following. The "key" is a 64 bit hexadecimal number in the format specified in the DES document, that is the high order 7 bits of each octet are used to form the 56 bit key while the low order bit of each octet is given a value such that odd parity is maintained for the octet. Leading zeroes must be specified (i.e. the key must be exactly 16 hex digits long) and odd parity must be maintained. Hence a zero key, in standard format, would be given as 0101010101010101 . The "key" is a 64 bit hexadecimal number in the format specified in the NTP standard. This is the same as the DES format except the bits in each octet have been rotated one bit right so that the parity bit is now the high order bit of the octet. Leading zeroes must be specified and odd parity must be maintained. A zero key in NTP format would be specified as 8080808080808080 The "key" is a 1|to|8 character ASCII string. A key is formed from this by using the lower order 7 bits of the ASCII representation of each character in the string, with zeroes being added on the right when necessary to form a full width 56 bit key, in the same way that encryption keys are formed from Unix passwords. The "key" is a 1|to|8 character ASCII string, using the MD5 authentication scheme. Note that both the keys and the authentication schemes (DES or MD5) must be identical between a set of peers sharing the same key number.

One of the keys may be chosen, by way of the configuration file requestkey statement, to authenticate run time configuration requests made using the xntpdc(8) program. The latter program obtains the key from the terminal as a password, so it is generally appropriate to specify the key chosen to be used for this purpose in ASCII format.

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 (configuring a reference clock with a peer statement can also be done, though with some clock drivers this may cause the clock to be treated somewhat differently and by convention is used for debugging purposes). 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 has been compiled in. Its 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 interpretation of these values, and whether they are used at all, is a function of the needs of the particular clock driver.

Xntpd on Unix machines currently supports several different types of clock hardware plus a special pseudo|clock used for backup or when no other clock source is available. The clock drivers, and the addresses used to configure them, are described following:

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 synchonize 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 fudge time1 parameter. 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 manually adjust the speed of the clock to maintain reasonable synchronization with, say, a voice time announcement. It is actually more useful to manipulate this value with the xntpdc(8) program.

127.127.3.u | Precision Standard Time 1010/1020 WWV/H Receiver

This driver can be used to receive time from a PST 1020 WWV receiver connected to a serial port on the computer. Any or all of four units, with unit numbers in the range 0 through 3, can be configured. The driver assumes the serial line the clock is connected to is /dev/pst%d (i.e. unit 1, at 127.127.3.1, opens /dev/pst1 to speak to the clock) and that the PST receiver is configured for 9600 baud operation.

The fudge time1 and time2 parameters are used by the driver as nominal propagation delays when synchronized to WWV and WWVH, respectively. They default to 0.0075 and 0.0265 seconds, values which are about right for Toronto. While this should in principle be set to the propagation delays appropriate for the location, one should not feel inhibited from tweaking the values to make the output of the clock match other stratum 1 NTP peers more exactly. The only consideration when adjusting these is that the difference between the values should be kept set to the predicted difference in propagation delay between WWV and WWVH at all times.

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 synchonization whenever it is operating, though higher values may be assigned if you only want the clock to provide backup service when all other primary sources have failed. The value2 parameter is set to the number of minutes which the daemon will allow the clock to go without synchronization before it starts disbelieving it. The default is 20, which is suitable if you have good quality backup NTP peers. If your network is isolated or your network connections are poor it might be advantageous to increase this value substantially.

The fudge flag1 can be set with good effect if your system clock's precision is worse than about 500 microseconds, as it causes the code processing algorithms to be modified slightly in a way which should produce better results with imprecise clocks. Setting fudge flag2 will force the driver to send to the clock the commands required to program the current WWV and WWVH fudge delays into it (this is normally done only when the values change). Setting the (otherwise undocumented) fudge flag3 will cause the driver to reset the clock. The latter two flags are generally only useful for debugging.

127.127.4.u | Spectracom 8170 and Netclock/2 WWVB Synchronized Clocks

This driver provides an interface to the Spectracom 8170 and Netclock/2 WWVB Synchronized Clocks in either Format|0 or Format|1 mode of operation at 9600 bps. The driver opens the RS232 output on /dev/wwvb%d, where %d is replaced by the unit number of the unit opened. 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.

The fudge time1 parameter is used as a general calibration factor for the clock, with positive values advancing the time and negative values retarding it. 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.

127.127.5.u | Kinemetrics TrueTime 468|DC Receiver This driver provides an interface to a Kinemetrics TrueTime 468|DC GOES receiver. opens /dev/goes%d to listen to the clock, where %d is the unit number of the clock to be opened.

Since the clock adjusts to compensate for radio delays, no fudging is usually needed. If you know the internal delay DIP switches are wrong for your location (i. e. set to factory default 50 when another setting is needed), you can manually advance/retard the clock with fudge time1.

While untested, this driver should work with all TrueTime receivers, since all use the same timecode.

127.127.7.u | Direct synchronization to the CHU timecode

Unlike the NIST time services, whose timecode requires quite specialized hardware to interpret, the CHU timecode can be received directly via a serial port after demodulation. While there are currently no commercial CHU receivers the hardware required to receive the CHU timecode is fairly simple to build. The driver supports four units, numbered 0 through 3, and opens /dev/chu%d to access the serial device the particular unit is connected to. While it is possible to configure several CHU units simultaneously this is not recommended as the character interrupts from all units will be occuring at the same time and will interfere with each other. Note that the operation of the CHU driver (and probably the ability to actually compile the driver into the daemon) requires that a special purpose CHU serial line discipline be installed in your kernel to take timestamps at interrupt level and to do noise prefiltering.

The CHU driver uses fudge time1 and time2 as calibration factors. By convention, time1 is the estimated propagation delay to CHU (the propdelay program in the distribution may be used to compute a rough estimate of this) while time2 is an estimate of propagation|independent delays through the modem filters and serial driver. These values default to 0.0025 and 0.0002 seconds, respectively, values which are suitable for Toronto and the modem I built. Fudge value1 can be set to the stratum you wish the clock peer to operate at. This defaults to zero, though a higher stratum can be set if the clock is only to be used for backup. If fudge flag1 is set a slightly different algorithm, better suited for machines where the system clock precision is coarser than about 500 microseconds, is selected for processing the raw data.

127.127.8.u | Synchronisation to several receivers (DCF77, GPS)

The timecode of the receivers will be sampled via a STREAMS module in the kernel (The STREAMS module has been designed for use with SUN Systems under SunOS 4.1.x. It can be linked directly into the kernel or loaded via the loadable driver mechanism) This STREAMS module can be adepted to be able to convert different time code formats. If the daemon is compiled without the STREAM definition synchronisation will work without the Sun streams module, though accuracy is significantly degraded.
The actual receiver status is mapped into various synchronisation states generally used by receivers. The STREAMS module is configured to interpret the time codes of DCF U/A 31, PZF535, GPS166, ELV DCF7000, Schmid and low cost receivers (see list below).
The reference clock support in xntp contains the necessary configuration tables for those receivers. In addition to supporting up to 32 different clock types and 4 devices the generation a a PPS signal is also provided as an configuration option. The PPS configuration option uses the receiver generated time stamps for feeding the PPS loopfilter control for much finer clock synchronisation.
CAUTION: The PPS configuration option is different from the hardware PPS signal, which is also supported (see below), as it controls the way xntpd is synchronised to the reference clock, while the hardware PPS signal controls the way time offsets are determined.
The use of the PPS option requires receivers with an accuracy of better than 1ms.

Fudge factors

Only two fudge factors are utilized. The time1 fudge factor defines the phase offset of the sychnronisation character to the actual time. The flag0 enables input filtering. This a median filter with continuous sampling. The flag1 selects averaging of the samples remaining after the filtering. Leap second handling is controlled with the flag2. When set a leap second will be deleted on receipt of a leap second indication from the receiver. Otherwise the leap second will be added (which is the default).

ntpq timecode variable

The timecode variable in the ntpq read clock variable command contains several fields. The first field is the local time in Unix format. The second field is the offset to UTC (format HHMM). The currently active receiver flags are listed next. Additional feature flags of the receiver are optionally listed in paranthesis. The actual time code is enclosed in angle brackets < >. A qualification of the decoded time code format is following the time code. The last piece of information is the overall running time and the accumulated times for the clock event states.

Unit encoding

The unit field <u> encodes the device, clock type and the PPS generation option. There are 4 possible devices which are encoded in the lower 2 bits of the <u> field. The devices are named /dev/refclock|0 through /dev/refclock|3. Bits 2 thru 6 encode the clock type. The fudge factors of the clock type are take from a table clockinfo in refclock_parse.c. The generation of PPS information for disciplining the local NTP clock is encoded in bit 7 of <u>.

Currently eight clock types (devices /dev/refclock|0 | /dev/refclock|3) are supported. Meinberg PZF535 receiver (FM demodulation/TCXO / 50us) Meinberg PZF535 receiver (FM demodulation/OCXO / 50us) Meinberg DCF U/A 31 receiver (AM demodulation / 4ms) ELV DCF7000 (sloppy AM demodulation / 50ms) Walter Schmid DCF receiver Kit (AM demodulation / 1ms) RAW DCF77 100/200ms pulses (Conrad DCF77 reciever module / 5ms) RAW DCF77 100/200ms pulses (TimeBrick DCF77 reciever module / 3ms) Meinberg GPS166 receiver (GPS / <<1us)

The reference clock support carefully monitors the state transitions of the receiver. All state changes and exceptional events such as loss of time code transmission are logged via the syslog facility. Every hour a summary of the accumulated times for the clock states is listed via syslog.

PPS support is only available when the receiver is completely synchronised. The receiver is believed to deliver correct time for an additional period of time after losing sychronisation unless a disruption in time code transmission is detected (possible power loss). The trust period is dependent on the receiver oscillator and thus a function of clock type. This is one of the parameters in the clockinfo field of the reference clock implementation. This parameter cannot be configured by xntpdc.

In addition to the PPS loopfilter control a true PPS hardware signal can be applied on Sun Sparc stations via the CPU serial ports on the CD pin. This signal is automatically detected and will be used for offset calculation. The input signal must be the time mark for the following time code. (The edge sensitivity can be selected | look into the appropriate kernel/parsestreams.c for details). Meinberg receivers can be connected by feeding the PPS pulse of the receiver via a 1488 level converter to Pin 8 (CD) of a Sun serial zs|port.

There exists a special firmware release for the PZF535 Meinberg receivers. This release (PZFUERL 4.6 (or higher | The UERL is important)) is absolutely recommended for XNTP use, as it provides LEAP warning, time code time zone information and alternate antenna indication. Please check with Meinberg for this firmware release.

The raw DCF77 pulses can be fed via a level converter directly into Pin 3 (Rx) of the Sun. The telegrams will be decoded an used for synchronisation. AM DCF77 receivers are running as low as $25. The accuracy is dependent on the receiver and is somewhere between 2ms (expensive) to 10ms (cheap). Upon bad signal reception of DCF77 sychronisation will cease as no backup oscillator is available as usually found in other reference clock receivers. So it is important to have a good place for the DCF77 antenna. For transmitter shutdowns you are out of luck unless you have other NTP servers with alternate time sources available.

FILES
the default name of the configuration file the conventional name of the drift file the conventional name of the key file

SEE ALSO

xntpdc(8), ntpq(8), ntpdate(8)

HISTORY

Written by Dennis Ferguson at the University of Toronto. Text amended by David Mills at the University of Delaware.

BUGS

Xntpd has gotten rather fat. While not huge, it has gotten larger than might be desireable for an elevated|priority daemon running on a workstation, particularly since many of the fancy features which consume the space were designed more with a busy primary server, rather than a high stratum workstation, in mind. This will eventually be corrected either by adopting the ntpd daemon as an alternative when it becomes able to match xntpd's performance, or if not than by producing a stripped down version of xntpd specifically for workstation use.