ntp.conf(4)ntp.conf(4)NAMEntp.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. Com‐
ments, 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 writ‐
ten 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 alter‐
natives 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 Administration
manual for more information. If you manually edit the ntp.conf file,
do not use the SysMan Menu to modify the configuration in the future.
The SysMan Menu recognizes only a small subset of the options that you
can use in the ntp.conf file, and might overwrite your configuration.
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 synchro‐
nized by the local server. This is useful in a network of servers
where, depending on various failure scenarios, either the local or
remote server host may be the better source of time. This command
specifies that the local server is to operate in “client” mode with the
remote server named in the command. In this mode, the local server can
be synchronized to the remote server, but the remote server can never
be synchronized to the local server. This command specifies that the
local server is to operate in broadcast mode where the local server
sends periodic broadcast messages to a client population at the broad‐
cast or multicast address named in the command. Ordinarily, this spec‐
ification applies only to the local server operating as a transmitter;
for operation as a broadcast client, see the broadcastclient or multi‐
castclient 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 mes‐
sages. 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 ser‐
vices. 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 min‐
imum and maximum polling interval for NTP messages, in seconds to the
power of two. The default range is 6 (64 seconds) to 10 (1024 sec‐
onds). 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 oper‐
ating 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 mea‐
sures 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 authentica‐
tion 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 off‐
set is assumed zero. In this case, it may take some hours for the fre‐
quency 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 cor‐
rectly authenticated using a trusted key and key identifier. The
default for this flag is disable (off). Causes the server to listen
for a message from a broadcast or multicast server, following which an
association is automatically instantiated for that server. The default
for this flag is disable (off). Enables the server to adjust its local
clock, with default enable (on). If not set, the local clock free-runs
at its intrinsic time and frequency offset. This flag is useful in
case the local clock is controlled by some other device or protocol and
NTP is used only to provide synchronization to other clients. Enables
the monitoring facility (see "Monitoring Options"), with default enable
(on). Enables statistics facility filegen, with default enable (on).
This command controls the amount and type of output written to the sys‐
tem 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 controlled: 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 con‐
trolled 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 synchroniza‐
tion 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 respec‐
tive multicast group(s). If none are given, the IP address
assigned to NTP (224.0.1.1) is assumed.
Authentication Options
Specifies the key identifier to use with the ntpq program, which is
useful to diagnose and repair problems that affect xntpd operation.
The operation of the ntpq program and xntpd conform to those specified
in RFC 1305. Requests from a remote ntpq program that affect the state
of the local server must be authenticated, which requires both the
remote program and local server share a common key and key identifier.
The argument to this command is a 32-bit unsigned integer. If no
requestkey command is included in the configuration file, or if the
keys do not match, such requests are ignored. Specifies the name of a
file that contains the encryption keys and key identifiers used by
xntpd when operating in authenticated mode. See ntp.keys(4) for
description of the key file format. Specifies the key identifier to
use with the xntpdc program, which is useful to diagnose and repair
problems that affect xntpd operation. The operation of the xntpdc pro‐
gram 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 pro‐
gram and local server share a common key and key identifier. The argu‐
ment to this command is a 32-bit unsigned integer. If no requestkey
command is included in the configuration file, or if the keys do not
match, such requests are ignored. Specifies the encryption key identi‐
fiers that are trusted for the purposes of authenticating peers suit‐
able for synchronization. The authentication procedures require that
both the local and remote servers share the same key and key identifier
for this purpose, although different keys can be used with different
servers. The arguments are 32-bit unsigned integers. Note, however,
that NTP key 0 is fixed and globally known. If meaningful authentica‐
tion 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 normally
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 redun‐
dant. The flags can generally be classed into two categories:
those that restrict time service and those that restrict infor‐
mational 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 ser‐
vice is not affected. Ignores all NTP mode 6 and 7 packets that
attempt to modify the state of the server (run time reconfigura‐
tion). 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 log‐
ging programs. Declares 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. 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, moni‐
toring 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, ntp‐
port, 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 imple‐
mented 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 circumvented 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 statis‐
tics are a typical example for such files. Generation file sets pro‐
vide access to a set of files used to store the actual data. At any
time, only one element of the set is being written to. The type given
specifies when and how data will be directed to a new element of the
set. This way, information stored in elements of a file set that are
currently unused are available for administrational operations without
the risk of disturbing the operation of xntpd. (The elements can be
removed to free space for new data produced.) File names of set members
are built from three elements: This is a constant filename path. It is
not subject to modifications by the filegen statement. It is defined
by the server, usually specified as a compile time constant. It may,
however, be configurable for individual file generation sets via other
commands. For example, the prefix used with loopstats and peerstats
filegens can be configured using the statsdir statement explained pre‐
viously. 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 filesys‐
tem hierarchy denoted by prefix. This part reflects individual ele‐
ments 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 follow‐
ing 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 mem‐
bers during runtime, however it provides an easy way of separat‐
ing files belonging to different xntpd server incarnations. The
set member filename is built by appending a dot (.) to concate‐
nated 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 con‐
tains 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 con‐
sists 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 speci‐
fied, 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 statistics 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 statis‐
tics information. This includes statistics records of all peers
of a NTP server and of the 1-pps signal, where present and con‐
figured. Each valid update appends a line of the following form
to the current element of a file generation set named “peer‐
stats”: 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 informa‐
tion. Each update received from a clock driver outputs a line
of the following form to the file generation set named “clock‐
stats”: 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 information specific to each clock for further details.
Statistic files are managed using file generation sets (see the
filegen description). The information obtained by enabling sta‐
tistics 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 genera‐
tion 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 pro‐
cessing 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 cali‐
bration 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. 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 additional variables serve
informational purposes only. They are not related to the proto‐
col other that they can be listed. The known protocol variables
always override any variables defined by the the setvar mecha‐
nism.
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
reference 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 infor‐
mation from the server in a log file. While such monitor pro‐
grams 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 vari‐
ables. The leap warning bits that can be set in the leapwarning vari‐
able (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 config‐
uration file. Typically, this is the only command necessary to config‐
ure 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 reference
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 fol‐
low 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 interpre‐
tation depends on the clock receiving it. A flag whose interpretation
depends on the clock receiving it. Enables detailed status monitoring
and event recording. The data collected are written to the clockstats
file maintained by the filegen utility (See xntpd(8)). This file is
normally processed by a cron job run once per day to produce summary
statistics and performance data.
The clock drivers, and the addresses used to configure them, are
described as follows:
127.127.1.u - Undisciplined Local Clock
This driver can have the following applications: Allow a machine to use
its own system clock as a reference clock, using no outside clock dis‐
cipline source. This is useful if you want to use NTP in an isolated
environment with no radio clock or NIST modem available. Choose a
machine that has a good clock oscillator and configure it with this
support. Set the clock using the best means available. Then, point all
the other machines at this one or use broadcast (not multicast) mode to
distribute time. You want to use a particular server's clock as the
clock of last resort when all other normal synchronization sources have
gone away. This is useful if that server has an ovenized oscillator.
For this you would configure this clock at a higher stratum (3 or 4) to
prevent the server's stratum from falling below that. An external dis‐
cipline 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 Synchro‐
nization Service (DTSS), which runs on DCE machines. In this case, set
the stratum to zero, indicating a bona fide stratum-1 source. Use this
with caution since there is no easy way to telegraph through NTP that
something might be wrong in the discipline source itself. In the case
of DTSS, the local clock can have a rather large jitter, depending on
the interval between corrections and the intrinsic frequency error of
the clock oscillator. In extreme cases, this can cause clients to
exceed the 128-ms slew window and drop off the NTP subnet.
In the default mode, the behavior of the clock selection algorithm is
modified when this support is in use. The algorithm is designed so
that the local clock support is not selected unless no other discipline
source is available. This can be overridden with the prefer keyword of
the server configuration command, in which case only this support is
selected for synchronization and all other discipline sources are
ignored. This behavior is intended for use when an external discipline
source controls the system clock.
Fudge Factors
By default, the stratum for this driver LCLSTRATUM is set at 5 and the
reference ID is set to LCL. Both can be changed by the fudge command
or the xntpdc utility. Never configure this driver to operate at a
stratum that might disrupt a client with access to a bona fide primary
server, unless the local clock oscillator is reliably disciplined by
another source. Never configure a server that might devolve to an
undisciplined local clock to use multicast mode.
This driver provides a mechanism to trim the local clock in both time
and frequency, as well as a way to manipulate the leap bits. The fudge
time1 parameter adjusts the time (in seconds) and the fudge time2
parameter adjusts the frequency (in ppm). Both parameters are addi‐
tive; that is, they add increments in time or frequency to the present
values. Note: The frequency cannot be changed when the kernel modifica‐
tions are in use. The fudge flag1 and fudge flag2 bits set the corre‐
sponding 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 automati‐
cally 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 sec‐
tions 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 fre‐
quencies 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 Syn‐
chronized 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 syn‐
chronization; 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 (?) indi‐
cates out of synchronization. Is a quality indicator. A space (" ")
indicates locked and A,B,C, or D indicates unlocked. Denotes year (as
broadcast). Denotes day of year. Denotes hours, minutes, seconds, and
milliseconds.
The alarm condition is indicated by other than " " at A, which occurs
during initial synchronization and when received signal is lost for
about ten hours. The unlock condition is indicated by other than " " at
Q.
The Q is normally " " when the time error is less than 1 ms, but either
A,B,C, or D when the time error is less than 10 ms, 100 ms, 500 ms, or
greater than 500 ms, respectively. The L is normally " ", but is set
to "L" early in the month of an upcoming UTC leap second and reset to '
' on the first day of the following month. The D is set to 'S' for
standard time 'I' on the day preceding a switch to daylight time, 'D'
for daylight time and 'O' on the day preceding a switch to standard
time. The start bit of the first <cr> is synchronized to the indicated
time as returned.
This driver interpolates the format in use from the length of the mes‐
sage. A three-stage median filter is used to reduce jitter and provide
a dispersion measure. The driver makes no attempt to correct for the
intrinsic jitter of the radio itself, which is a known problem with the
older radios.
Fudge Factors
This driver can retrieve a table of quality data maintained internally
by the Netclock/2 receiver. If flag4 of the fudge configuration com‐
mand 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 timecode
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 millisec‐
ond 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 Inter‐
net 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 compatible
modem.
The accuracy produced by this driver should be in the range of a mil‐
lisecond 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. Ini‐
tial 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 interfaces
may work as well. The ACTS telephone number and modem setup string are
hard-coded in the driver and may require changes for nonstandard modems
or special circumstances.
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 man‐
ual 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 con‐
figuration 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 call‐
ing 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 ref‐
erence time of the timecode. If a message with an on-time character of
# is received, the driver updates the propagation delay. The driver
disconnects when ten valid messages have been received, no message has
been received for 15 seconds, or an # on-time character is received.
These messages are processed by a trimmed-mean filter to reduce timing
noise and then by the usual NTP algorithms to develop the clock correc‐
tion.
The behavior of the clock selection algorithm is modified when this
driver is in use. The algorithm is designed so that this driver will
never be selected unless no other discipline source is available. This
can be overridden with the prefer keyword of the server configuration
command, in which case only this driver will be selected for synchro‐
nization and all other discipline sources will be ignored. Ordinarily,
the prefer keyword is used only in automatic mode when primary time is
to be obtained through ACTS, and backup NTP peers used only when ACTS
fails.
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 system
involved; you might have to experiment.
Manual call attempts can be made at any time by setting fudge flag1
using xntpdc. For example, the following xntpdc command asks for a key
identifier and password and, if authenticated by the server, sets
flag1: fudge 127.127.18.1 flags 1
There might be a short delay until the expiration of the current poll
timeout.
The flag1 can be set from a cron job using the following steps: Create
a file with the following contents: keyid 11 passwd dialup fudge
127.127.18.1 flags 1 quit Run the following program at specified times
as required: /usr/local/bin/xntpdc file
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: Services delim off
ntp.conf(4)