ntp.conf(4) Kernel Interfaces Manual ntp.conf(4)
NAME
ntp.conf - Network Time Protocol (NTP) configuration file
DESCRIPTION
The xntpd configuration file, /etc/ntp.conf, is read by xntpd at startup.
The xntpd configuration file is relatively free of formatting. 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 argu-
ments are delimited by "[]" in the following descriptions, while alternatives are separated by "|".
The /etc/ntp.conf file is defined as a Context-Dependent Symbolic Link (CDSL), and must be maintained as such. See the System Administra-
tion manual for more information.
Configuration Options
peer host_address [key #] [version #] [burst] [prefer] [minpoll #] [maxpoll #] server host_address [key #] [burst] [version #] [prefer]
[mode #] [minpoll #] [maxpoll #] broadcast host_address [key #] [burst] [version #] [minpoll #] [maxpoll #] [ttl #] manycastclient
host_address [key #] [burst] [version #] [minpoll #] [maxpoll #] [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 spec-
ifies 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 broad-
cast or multicast address named in the command. Ordinarily, this specification applies only to the local server operating as a transmit-
ter; 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 224.0.1.1 is assigned to NTP; this is
presently the only number that should be used. This command specifies that the local server is to operate in client mode with the remote
servers that are discovered as a result of broadcast/multicast messages. The client broadcasts a request message to the specified group
address and specifically-enabled servers respond to these messages. The client selects the servers providing the best time and continues as
with the server command. The remaining servers are discarded as if never heard. In this mode, the supplied host_address must match the
address used on the manycastserver command for the designated manycast servers. The NTP multicast address (224.0.1.1) should not be used,
unless specific means are taken to avoid spraying large areas of the Internet with these messages and causing a possibly massive implosion
of replies at the sender.
The following options can be specified with these commands: Indicates that, at each poll interval, the server is to send a burst of eight
packets instead of one. This option is useful for maintaining accuracy over the intermittent connections that are typical of PPP and ISDN
services. 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. Specify the minimum and maximum polling interval for NTP messages, in sec-
onds to the power of two. The default range is 6 (64 seconds) to 10 (1024 seconds). The allowable range is 4 (16 seconds) to 17 (36.4 h)
inclusive. 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).
Additional Configuration Options
Directs the local server to listen for broadcast messages on the local network, in order to discover other servers on the same subnet.
Upon hearing a broadcast message for the first time, the local server 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 moni-
toring facility (see "Monitoring Options"), with default enable (on). Enables statistics facility filegen, with default enable (on). This
command controls the amount and type of output written to the system syslog facility or the alternate logfile log file. By default, only
minimal output is written.
All configkeyword keywords can be prefixed with =, + and -, where = sets the syslogmask, + adds and - removes messages. The syslog
messages can be controlled in four classes: clock, peer, sys and sync. Within these classes, four types of messages can be con-
trolled: info, events, statistics, and status.
Informational messages (info) control configuration information. Event messages (events) control logging of events (reachability,
synchronization, alarm conditions). Statistical output is controlled with the statistics keyword. The final message group is for
status messages, which mainly describe the synchronization status.
Configuration keywords are formed by concatenating the message class with the event class. The all prefix can be used instead of a
message class. A message class may also be followed by the all keyword to enable/disable all messages of the respective message
class. Thus, a minimal log configuration could look like this: logconfig = syncstatus +sysevents
This configuration, the default for the operating system, lists only the synchronization state of xntpd and major system events.
For a simple reference server, the following minimum message configuration could be useful: logconfig = syncall +clockall
This configuration lists all clock information and synchronization information. All other events and messages about peers, system
events and so on are suppressed. This command specifies the location of an alternate log file to be used instead of the default
system syslog facility. This command directs the local server to listen for and respond to broadcast messages received on any local
interface, and in addition enables the server to respond to client mode messages sent to the multicast group address(es) specified.
At least one address is required, but the NTP multicast address (224.0.1.1) should NOT be used, unless specific means are taken to
limit the span of the reply and avoid a possibly massive implosion at the original sender. This command is used in the same way as
the broadcastclient command, but operates using IP multicasting. Support for this function requires a multicast kernel and the use
of authentication. If one or more IP addresses are given, the server joins the respective multicast group(s). If none are given,
the IP address assigned to NTP (224.0.1.1) is assumed.
Authentication Options
Indicates the amount of time it takes to encrypt an NTP authentication field on the local computer. This value is used to correct transmit
time stamps when the authentication is used on outgoing packets. The value usually in the range of 0.0001 seconds to 0.003 seconds, though
it is very dependent on the CPU speed of the host computer. This value is calculated and inserted into the ntp.conf file by the ntpsetup
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 iden-
tifiers 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 encryp-
tion 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 mean-
ingful authentication is to be performed the 0 key should not be trusted.
Access Control Options
Defines the number of clients from the same network that are allowed to use the server. The default is 3. Specifies the number of seconds
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 restric-
tion 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 nor-
mally given in dotted-quad format, the text string default, with no mask option, may be used to indicate the default entry.
In the current implementation, flags always restrict access: an entry with no flags indicates that free access to the server is to
be given. The flags are not orthogonal, in that more restrictive flags will often make less restrictive ones redundant. The flags
can generally be classed into two categories: those that restrict time service and those that restrict informational queries. One
or more of the following flags may be specified: Ignores all packets from hosts that match this entry. If this flag is specified,
queries and time server polls receive no response. Ignores all NTP mode 6 and 7 packets (information queries and configuration
requests) from the source. Time service is not affected. Ignores all NTP mode 6 and 7 packets that attempt to modify the state of
the server (run time reconfiguration). Queries that return information are permitted. Declines to provide mode 6 control message
trap service to matching hosts. The trap service is a subsystem of the mode 6 control message protocol, which is intended for use
by remote event logging programs. Declares traps set by matching hosts to be low priority. The number of traps a server can main-
tain 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. Ignores NTP packets whose mode is other than 6 or 7. In effect, time service is denied,
though queries may still be permitted. Provides stateless time service to polling hosts, but does not allocate peer memory
resources to these hosts even if they otherwise might be considered useful as future synchronization partners. Treats these hosts
normally in other respects, but never uses them as synchronization sources. Limits the number of clients that can use these hosts
from the same net. Net in this context refers to the IP notion of net (class A, class B, class C, etc.). Only the first
clientlimit hosts that have accessed the server and that have been active during the last clientperiod seconds are accepted.
Requests from other clients from the same net are rejected. Only time request packets are taken into account. Private, control,
and broadcast packets are not subject to client limitation and therefore do not contribute to client count. History of clients is
kept using the monitoring capability of xntpd. Thus, monitoring is active as long as there is a restriction entry with the limited
flag. Specifies a match algorithm modifier, rather than a restriction flag. Its presence causes the restriction entry to be
matched only if the source port in the packet is the standard NTP UDP port (123). Both ntpport and non-ntpport may be specified.
The ntpport is considered more specific and is sorted later in the list.
Default restriction list entries, with the flags ignore, 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 (everything besides your own NTP server is
unrestricted).
The restriction facility allows the current access policies of the time servers running on the NSFnet backbone to be implemented
with xntpd as well. While this facility may be otherwise useful for keeping unwanted time servers from affecting your own, it
should not be considered an alternative to the standard NTP authentication facility. Source address based restrictions can be cir-
cumvented by a determined cracker.
Monitoring Options
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 sta-
tistics 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 with-
out 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.
A file generation set is characterized by its type. The following types are supported: The file set is a single plain file. One
element of file set is used per incarnation of a xntpd server. This type does not perform any changes to file set members during
runtime, however it provides an easy way of separating files belonging to different xntpd server incarnations. The set member file-
name is built by appending a dot (.) to concatenated prefix and filename strings, and appending the decimal representation of the
process id of the xntpd server process. One file generation set element is created per day. The term day is based on UTC. A day
is defined as the period between 00:00 and 24:00 UTC. The file set member suffix consists of a dot (.) and a day specification in
the following form: YYYYMMDD YYYY is a four-digit year number (for example, 1992); MM is a two-digit month number; and DD is a two-
digit day number. Thus, information written at December 10th, 1992 would be written to a file named prefixfilename.19921210. Any
file set member contains data related to a certain week of a year. The term week is defined by computing "day of year" modulo 7.
Elements of such a file generation set are distinguished by appending the following suffix to the file set filename base: A dot, a
four-digit year number, the letter W, and a two-digit week number. For example, information from January, 10th 1992 would be writ-
ten to a file with suffix One generation file set element is generated per month. The file name suffix consists of a dot, a four-
digit year number, and a two-digit month. One generation file element is generated per year. The filename suffix consists of a dot
and a four-digit year number. This type of file generation sets changes to a new element of the file set every 24 hours of server
operation. The filename suffix consists of a dot, the letter a, and an eight-digit number. This number is taken to be the number
of seconds the server is running at the start of the corresponding 24 hour period.
Information is only written to a file generation set when this set is enabled. Output is prevented by specifying disable.
It is convenient to be able to access the current element of a file generation set by a fixed name. This feature is enabled by
specifying link and disabled using nolink. If link is 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. Enables writing of statistics records. The following types of sta-
tistics are supported: Enables recording of loop filter statistics information. Each update of the local clock outputs a line of
the following form to the file generation set named "loopstats": 48773 10847.650 0.0001307 17.3478 2
The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next three fields
show time offset in seconds, frequency offset in parts-per-million and time constant of the clock-discipline algorithm at each
update of the clock. Enables recording of peer statistics information. This includes statistics records of all peers of a NTP
server and of the 1-pps signal, where present and configured. 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 Day) and time (seconds and fraction past UTC midnight). The next two fields
show the peer address in dotted-quad notation and status, respectively. The status field is encoded in hex in the format described
in Appendix A of the NTP specification RFC 1305. The final three fields show the offset, delay and dispersion, all in seconds.
Enables recording of clock driver statistics information. Each update received from a clock driver outputs a line of the following
form to the file generation set named "clockstats": 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next field shows
the clock address in dotted-quad notation, The final field shows the last timecode received from the clock in decoded ASCII format,
where meaningful. In some clock drivers a good deal of additional information can be gathered and displayed as well. See informa-
tion specific to each clock for further details.
Statistic files are managed using file generation sets (see the filegen description). The information obtained by enabling statis-
tics recording allows analysis of temporal properties of a xntpd server. It is usually only useful to primary servers or maybe main
campus servers. Enables recording of raw-timestamp statistics information. This includes statistics records of all peers of a NTP
server and of special signals, where present and configured. Each NTP message received from a peer or clock driver appends a line of
the following form to the file generation set named rawstats: 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000
3102453281.58622800031 02453332.540806000 3102453332.541458000
The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next two fields show
the remote peer or clock address followed by the local address in dotted-quad notation. The final four fields show the originate,
receive, transmit and final NTP timestamps in order. The timestamp values are as received and before processing by the various data
smoothing and mitigation algorithms. Indicates the full path of a directory where statistics files should be created. This keyword
allows the (otherwise constant) filegen filename prefix to be modified for file generation sets used for handling statistics logs
(see the description of the filegen statement).
Miscellaneous Options
Specifies the default delay to be used in cases where the delay 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.
The broadcast and multicast modes require a special calibration to determine the network delay between the local and remote servers.
Ordinarily, this is done automatically by the initial protocol exchanges between the local and remote servers. monitor yes|no
authenticate yes|no These commands have been superseded by the enable and disable commands. They are listed here for historical
purposes. Specifies the nominal precision of the local clock. The value is an integer approximately equal to the base 2 logarithm
of the local timekeeping precision in seconds. Normally, the daemon determines the precision automatically at startup, so this com-
mand is necessary only in special cases when the precision cannot be determined automatically. Adds an additional system variable.
These variables can be used to distribute additional information such as the access policy. If the variable of the form name=value
is followed by the default keyword, the variable is listed as part of the default system variables (ntpq rv command). These addi-
tional variables serve informational purposes only. They are not related to the protocol other that they can be listed. The known
protocol variables always override any variables defined by the the setvar mechanism.
There are three special variables that contain the names of all variables of the same group. The sys_var_list holds the names of
all system variables. The peer_var_list holds the names of all peer variables and the clock_var_list hold the names of the refer-
ence clock variables. trap host_address [port port_number] [interface interface_address] Configures a trap receiver at the given
host address and port number, sending messages with the specified local interface address. If the port number is unspecified, a
value of 18447 is used. If the interface address is not specified, the message is sent with a source address (the local interface
the message is sent through). On a multihomed host, the interface used may vary from time to time with routing changes.
The trap receiver generally logs event messages and other information from the server in a log file. While such monitor programs
may also request their own trap dynamically, configuring a trap receiver ensures that no messages are lost when the server is
started.
Variables
Most variables used by the NTP protocol can be examined with the xntpdc (mode 7 messages) and the ntpq (mode 6 messages). Currently very
few variables can be modified by using mode 6 messages. These variables are either created with the setvar directive or the leap warning
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).
Reference Clock Support
The xntpd daemon includes support for a number of types of reference clocks. A reference clock is generally (though not always) a radio
timecode receiver that is synchronized to a source of standard time, such as the services offered by the NRC in Canada and NIST in the U.S.
The interface between the computer and the timecode receiver is device dependent and will vary, but is often a serial port.
For configuration purposes, xntpd treats reference clocks like normal NTP peers. However, unlike normal peers, reference clocks are
referred to by an invalid IP address.
Reference clock addresses are of the form 127.127.t.u, where t is an integer denoting the clock type and u indicates the type-specific unit
number, in the range 0-3, that is used to identify multiple instances of clocks of the same type. Most of these clocks require support in
the form of a serial port or special bus peripheral. The particular 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:
-----------------------------------------------------------------
Type Device Name Description
-----------------------------------------------------------------
1 (none) LOCAL Undisciplined Local Clock
3 pst WWV_PST PSTI/Traconex WWV/WWVH Receiver
4 wwvb WWVB_SPEC Spectracom WWVB Receiver
5 true TRUETIME TrueTime GPS/GOES/OMEGA Receivers
15 true TRUETIME TrueTime Generic Receivers (alias)
18 acts NIST_ACTS NIST Automated Computer Time Service
25 true TRUETIME TrueTime Generic Receivers (alias)
-----------------------------------------------------------------
Although clock types 15 and 25 still exist as aliases for TrueTime clocks, it is best to use type 5, because the aliases might change in
the future.
Reference clocks are configured using a server statement in the configuration file. Typically, this is the only command necessary to con-
figure a reference clock. The following is the format for this command: server 127.127.t.u [prefer] [mode m] [minpoll #] [maxpoll #]
In the preceding command: Specifies the clock type number. Specifies the unit number. This is typically 1, but can range from 0-3. Modi-
fies the clock selection algorithm. Specifies a clock mode for those clock drivers that support multiple modes of operation. Specifies
the minimum and maximum polling interval for reference clock messages, in seconds to the power of two. For most directly connected refer-
ence clocks, both minpoll and maxpoll default to 6 (64 seconds). For modem reference clocks, minpoll defaults to 10 (147.1 minutes) and
maxpoll defaults to 14 (4.5 hours). The allowable range is 4 (16 seconds) to 17 (36.4 hours) inclusive.
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 [time1 secs] [time2 secs] [stratum #] [refid id] [mode #] [flag1 0|1] [flag2 0|1] [flag4 0|1] 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. Specifies a mode number which is
interpreted in a device-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the parse
drivers. 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. A flag whose inter-
pretation depends on the clock receiving it. A flag whose interpretation depends on the clock receiving it. Enables detailed status moni-
toring 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 oscil-
lator. 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 key-
word 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.
Fudge Factors
By default, the stratum for this driver LCLSTRATUM is set at 3 and the reference ID is set to LCL. Both can be changed by the fudge com-
mand 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.3.u - PSTI/Traconex WWV/WWVH Receiver
This driver supports the PSTI 1010 and Traconex 1020 WWV/WWVH Receivers. No specific claim of accuracy is made for these receivers, but
actual experience suggests that 10 ms would be a conservative assumption.
The DIP switches should be set for 9600 bps line speed, 24-hour day-of-year format and UTC time zone. Automatic correction for DST should
be disabled. It is very important that the year be set correctly in the DIP switches; otherwise, the day of year will be incorrect after 28
April of a normal or leap year. The propagation delay DIPswitches should be set according to the distance from the transmitter for both WWV
and WWVH, as described in the instructions. While the delay can be set only to within 11 ms, the fudge time1 parameter can be used for
vernier corrections.
Using the poll sequence QTQDQM, the response timecode is in three sections totaling 50 ASCII printing characters, as concatenated by the
driver, in the following format: ahh:mm:ss.fffs<cr> yy/dd/mm/ddd<cr> frdzycchhSSFTttttuuxx<cr> In the preceding format: Is an AM/PM indica-
tor. If this is a space (" "), it indicates 24-hour mode. Denotes hours, minutes, seconds, and milliseconds. LI "s" Is a daylight-saving
indicator. If this is a space (" "), it indicates 24-hour mode. Denotes on-time. Denotes year (from DIP switches). Denotes day of
month, month, and day of year. Denotes frequency enable (O = all frequencies enabled). Denotes baud rate (3 = 1200, 6 = 9600). Is a fea-
tures indicator (@ = month/day display enabled). Denotes time zone (0 = UTC). Denotes year (5 = 91). Denotes WWV propagation delay (52 =
22 ms). Denotes WWVH propagation delay (81 = 33 ms). Denotes status (80 or 82 = operating correctly). Denotes current receive frequency
(4 = 15 MHz). Denotes transmitter (C = WWV, H = WWVH). Denotes time since last update (0000 = minutes). Denotes flush character (03 =
^c). Denotes 94 (unknown).
The alarm condition is indicated by other than '8' at A, which occurs during initial synchronization and when received signal is lost for
an extended period; unlock condition is indicated by other than "0000" in the tttt subfield at Q.
Fudge Factors
Only generic fudge factors apply.
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 indi-
cated 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 pro-
vide a dispersion measure. The driver makes no attempt to correct for the intrinsic jitter of the radio itself, which is a known problem
with the older radios.
Fudge Factors
This driver can retrieve a table of quality data maintained internally by the Netclock/2 receiver. If flag4 of the fudge configuration
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.5.u - TrueTime GPS/GOES/OMEGA Receivers
This driver supports several models of Kinemetrics/TrueTime Timing Receivers, including the 468-DC MK III GOES Synchronized Clock, GPS- DC
MK III and GPS/TM-TMD GPS Synchronized Clock, XL-DC (a 151-602-210, reported by the driver as a GPS/TM-TMD), GPS-800 TCU (an 805-957 with
the RS232 Talker/Listener module), OM-DC OMEGA Synchronized Clock, and very likely others in the same model family that use the same time-
code format.
These 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.5.1 opens the clock at /dev/true1) and that the clock is
configured for 9600-baud operation.
TrueTime clocks have the following timecode format: ADDD:HH:MM:SSQCL
In the preceding format: Denotes control-A (^A), which is stripped before the user sees it. Denotes day of year. Denotes hours, minutes,
and seconds. Is a quality indicator. Denotes carriage return, or on time. Start bit begins on 0 seconds and extends to 1 bit time.
Denotes line feed.
The quality codes report the following offsets for all receivers: +/- 500 milliseconds +/- 50 milliseconds +/- 5 milliseconds +/- 1 mil-
lisecond Less than 1 millsecond
The OM-DC OMEGA Receiver adds the following codes: +/- 1 second Less than 1 millisecond. Indicates which station is being received as fol-
lows: Norway Liberia Hawaii North Dakota La Reunion Argentina Australia Japan
Notes on 468-DC and OMEGA receiver:
Send the clock an R or C, and once per second a timestamp will appear. Send an R to get the satellite position once (GOES only).
Notes on the 468-DC receiver:
Since the old east/west satellite locations are only historical, you cannot set your clock propagation delay settings correctly and still
use automatic mode. The manual says to use a compromise when setting the switches. This results in significant errors. The solution is to
use fudge time1 and time2 to incorporate corrections. If your clock is set for 50 and it should be 58 for using the west and 46 for using
the east, use the following fudge line: fudge 127.127.5.0 time1 +0.008 time2 -0.004
This corrects the 4 milliseconds advance and 8 milliseconds retard needed. The software will ask the clock which satellite it sees.
Fudge Factors
Only generic fudge factors apply.
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 configura-
tion, and is specified by the phone command in the configuration file. The argument to this command is an AT command for a Hayes compati-
ble 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 characteris-
tics of the individual modem involved. For undetermined reasons, some modems work with the ACTS echo-delay measurement scheme and some do
not. This driver tries to do the best it can with what it gets. 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 (auto-
matic), the driver operates continuously at intervals depending on the prediction error, as measured by the driver, usually in the order of
several hours. In mode 1, (backup) the driver is enabled in automatic mode only when no other source of synchronization is available and
when more than MAXOUTAGE (3600 s) have elapsed since last synchronized by other sources. In mode 2, (manual) the driver operates only when
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 inter-
faces may work as well. The ACTS telephone number and modem setup string are hard-coded in the driver and may require changes for nonstan-
dard modems or special circumstances.
Fudge Factors
Ordinarily, the propagation time correction is computed automatically by ACTS and the driver. When this is not possible or erratic due to
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 char-
acter 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 configura-
tion command, in which case only this driver will be selected for synchronization and all other discipline sources will be ignored. Ordi-
narily, the prefer keyword is used only in automatic mode when primary time is to be obtained through ACTS, and backup NTP peers used only
when ACTS fails.
Call Management
Since ACTS is a toll call in most areas of the country, it is necessary to carefully manage the calling interval. The ACTS call program is
initiated by setting fudge flag1. This flag can be set manually using xntpdc, by a cron job that calls xntpdc, or automatically by the
driver itself. The fudge flag1 is reset when the program terminates after a time determination is complete or when no more numbers remain
in the alternate path list; a device fault or timeout has occurred; or the fudge flag1 has been reset using xntpdc.
In automatic and backup modes, the driver determines the call interval using a procedure depending on the measured prediction error and the
fudge time2 parameter. If the error exceeds time2 for a number of times depending on the current interval, the interval is decreased, but
not less than about 1000 seconds. If the error is less than time2 for some number of times, the interval is increased, but not more than
about 18 hours. With the default value of zero for fudge time2, the interval increases from 1000 seconds to the 4000-8000 second range, in
which the expected accuracy should be in the 1-2 ms range. Setting fudge time2 to a large value, like 0.1 second, may result in errors of
that order, but increase the call interval to the maximum. The exact value for each configuration depends on the modem and operating sys-
tem 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
FILES
Default name of the configuration file Conventional name of the drift file Conventional name of the key file
RELATED INFORMATION
Commands: ntp(1), ntpdate(8), ntpq(8), xntpd(8), xntpdc(8)
Files: ntp.keys(4)
Network Administration delim off
ntp.conf(4)