ntp.conf - Network Time Protocol (NTP) configuration file
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 arguments 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 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 [Toc] [Back]
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 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
broadcast or multicast address named in the command.
Ordinarily, this specification applies only to the local
server operating as a transmitter; 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 seconds 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 [Toc] [Back]
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 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 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
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 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 [Toc] [Back]
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 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 encryption 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 meaningful
authentication is to be performed the 0 key should not be
trusted.
Access Control Options [Toc] [Back]
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 restriction entry and then compared with the
entry's address (which has also been and'ed with the mask)
to look for a match. The mask argument defaults to
255.255.255.255, meaning that the address is treated as
the address of an individual host. A default entry
(address 0.0.0.0, mask 0.0.0.0) is always included and,
given the sort algorithm, is always the first entry in the
list. Note that, while address is normally given 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 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, 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 circumvented by a
determined cracker.
Monitoring Options [Toc] [Back]
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 statistics are a
typical example for such files. Generation file sets provide
access to a set of files used to store the actual
data. At any time, 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
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 filename 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 written
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 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 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 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 statistics 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 [Toc] [Back]
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.
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 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 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 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 [Toc] [Back]
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 [Toc] [Back]
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 configure 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. Modifies 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 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 interpretation 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 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 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 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 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 3 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 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 indicator.
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
features 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 indicated
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 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 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 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 millisecond 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 follows: 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 configuration,
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 millisecond or two, but may need correction due
to the delay characteristics 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 (automatic), 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 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 ontime
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 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 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 configuration command,
in which case only this driver will be selected for
synchronization 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
Default name of the configuration file Conventional name
of the drift file Conventional name of the key file
Commands: ntp(1), ntpdate(8), ntpq(8), xntpd(8), xntpdc(8)
Files: ntp.keys(4)
Network Administration: Services delim off
ntp.conf(4)
[ Back ] |
