 |
Index for
Section 4 |
|
 |
Alphabetical
listing for N |
|
 |
Bottom of
page |
|
ntp.conf(4)
NAME
ntp.conf - Network Time Protocol (NTP) configuration file
DESCRIPTION
The xntpd configuration file, /etc/ntp.conf, is read by xntpd at startup.
The xntpd configuration file is relatively free of formatting. Comments,
which may be freely inserted, begin with a # character and extend to the
end of the line. Blank lines are ignored. Configuration commands consist
of an initial keyword followed by a list of arguments, separated by white
space. Configuration commands may not be continued over multiple lines.
Arguments may be host names, host addresses written in numeric, dotted-quad
form, integers, floating point numbers (when specifying times in seconds)
and text strings. Optional 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.
Note
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:
peer
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.
server
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.
broadcast
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.
manycastclient
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:
burst
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.
key #
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.
version #
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.
minpoll #
maxpoll #
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.
prefer
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.
ttl #
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
broadcastclient
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.
disable auth|bclient|pll|monitor|stats [...]
Provides a way to disable various server options. Flags not mentioned
are unaffected. The flags presently available are described under the
enable command.
driftfile filename
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).
Note
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.
enable auth|bclient|pll|monitor|stats [...]
Provides a way to enable various server options. Flags not mentioned
are unaffected.
auth
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).
bclient
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).
pll 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.
monitor
Enables the monitoring facility (see "Monitoring Options"), with
default enable (on).
stats
Enables statistics facility filegen, with default enable (on).
logconfig configkeyword
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.
logfile filename
This command specifies the location of an alternate log file to be used
instead of the default system syslog facility.
manycastserver [IP address ...]
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.
multicastclient [IP address ...]
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
controlkey #
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.
keys filename
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.
requestkey #
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.
trustedkey # [# ...]
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
clientlimit limit
Defines the number of clients from the same network that are allowed to
use the server. The default is 3.
clientperiod period
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.
restrict address [mask numeric_mask] [flag] [...]
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:
ignore
Ignores all packets from hosts that match this entry. If this flag
is specified, queries and time server polls receive no response.
noquery
Ignores all NTP mode 6 and 7 packets (information queries and
configuration requests) from the source. Time service is not
affected.
nomodify
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.
notrap
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.
lowpriotrap
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.
noserve
Ignores NTP packets whose mode is other than 6 or 7. In effect,
time service is denied, though queries may still be permitted.
nopeer
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.
notrust
Treats these hosts normally in other respects, but never uses them
as synchronization sources.
limited
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.
ntpport
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
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:
prefix
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.
filename
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.
suffix
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:
none
The file set is a single plain file.
pid 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.
day 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.
week
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 .1992W1.
month
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.
year
One generation file element is generated per year. The filename
suffix consists of a dot and a four-digit year number.
age 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.
statistics name ...
Enables writing of statistics records. The following types of
statistics are supported:
loopstats
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.
peerstats
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.
clockstats
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.
rawstats
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.
statsdir /directory path/
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
broadcastdelay seconds
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.
setvar variable [default]
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).
Note
On a multihomed host, the interface used may vary from time
to time with routing changes.
The trap receiver generally logs event messages and other information
from the server in a log file. While such monitor programs may also
request their own trap dynamically, configuring a trap receiver ensures
that no messages are lost when the server is started.
Variables
Most variables used by the NTP protocol can be examined with the xntpdc
(mode 7 messages) and the ntpq (mode 6 messages). Currently very few
variables can be modified by using mode 6 messages. These variables are
either created with the setvar directive or the leap warning variables.
The leap warning bits that can be set in the leapwarning variable (up to
one month ahead). Both, the leapwarning and in the leapindication
variable, have a slightly different encoding than the usual leap bits
interpretation:
00 The daemon passes the leap bits of its synchronization source (usual
mode of operation).
01/10
A leap second is added/deleted (operator forced leap second).
11 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)
________________________________________________________________
Note
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:
t Specifies the clock type number.
u Specifies the unit number. This is typically 1, but can range from 0-
3.
prefer
Modifies the clock selection algorithm.
mode m
Specifies a clock mode for those clock drivers that support multiple
modes of operation.
minpoll #
maxpoll #
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]
time1 secs
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.
time2 secs
Specifies a fixed-point decimal number that is interpreted in a clock-
dependent way.
mode #
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.
stratum #
Specifies a number in the range 0 (zero) to 15, if you want to override
the default stratum assigned by xntpd.
refid id
Specifies a four-character, null-terminated ASCII string, if you want
to override the default reference identifier assigned by xntpd.
flag1
A flag whose interpretation depends on the clock receiving it.
flag2
A flag whose interpretation depends on the clock receiving it.
flag4
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:
a Is an AM/PM indicator. If this is a space (" "), it indicates 24-hour
mode.
hh:mm:ss.fff
Denotes hours, minutes, seconds, and milliseconds. LI "s" Is a
daylight-saving indicator. If this is a space (" "), it indicates 24-
hour mode.
first <cr>
Denotes on-time.
yy Denotes year (from DIP switches).
dd/mm/ddd
Denotes day of month, month, and day of year.
f Denotes frequency enable (O = all frequencies enabled).
r Denotes baud rate (3 = 1200, 6 = 9600).
d Is a features indicator (@ = month/day display enabled).
z Denotes time zone (0 = UTC).
y Denotes year (5 = 91).
cc Denotes WWV propagation delay (52 = 22 ms).
hh Denotes WWVH propagation delay (81 = 33 ms).
SS Denotes status (80 or 82 = operating correctly).
F Denotes current receive frequency (4 = 15 MHz).
T Denotes transmitter (C = WWV, H = WWVH).
tttt
Denotes time since last update (0000 = minutes).
uu Denotes flush character (03 = ^c).
xx 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:
first <cr>
Denotes on-time.
hh:mm:ss Denotes hours, minutes, and seconds.
i 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:
<cr> Denotes on-time.
i Is a synchronization flag. A space (" ") indicates in
synchronization; a question mark (?) indicates out of
synchronization.
q Is a quality indicator. A space (" ") indicates locked and
A,B,C, or D indicates unlocked.
yy Denotes year (as broadcast).
ddd Denotes day of year.
hh:mm:ss.fff
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:
A Denotes control-A (^A), which is stripped before the user sees
it.
ddd Denotes day of year.
HH:MM:SS Denotes hours, minutes, and seconds.
Q Is a quality indicator.
C Denotes carriage return, or on time. Start bit begins on 0
seconds and extends to 1 bit time.
L Denotes line feed.
The quality codes report the following offsets for all receivers:
? +/- 500 milliseconds
# +/- 50 milliseconds
* +/- 5 milliseconds
. +/- 1 millisecond
space Less than 1 millsecond
The OM-DC OMEGA Receiver adds the following codes:
> +/- 1 second
A-H Less than 1 millisecond. Indicates which station is being
received as follows:
A Norway
B Liberia
C Hawaii
D North Dakota
E La Reunion
F Argentina
G Australia
H 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:
jjjjj Denotes the modified Julian day.
yy-mm-dd Denotes the year, month, and day.
hh:mm:ss Denotes the hours, minutes, and seconds.
tt Is the DST indicator (see driver listing).
l Is the leap-second warning (see driver listing).
uuu Denotes DUT1 correction (see driver listing).
mmmmm Denotes modem calibration (see driver listing).
* Denotes an on-time character.
The timecode message is transmitted continuously after a signon banner,
which this driver ignores. The driver also ignores all but the yy-mm-dd,
hh:mm:ss and on-time character (*) fields, although it checks the format of
all fields of the message. A time stamp is captured at the * character, as
required by the ACTS specification, and used as the reference time of the
timecode. If a message with an on-time 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:
1. Create a file with the following contents:
keyid 11
passwd dialup
fudge 127.127.18.1 flags 1
quit
2. Run the following program at specified times as required:
/usr/local/bin/xntpdc file
FILES
/etc/ntp.conf
Default name of the configuration file
/etc/ntp.drift
Conventional name of the drift file
/etc/ntp.keys
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
|
Index for
Section 4 |
|
|
Alphabetical
listing for N |
|
 |
Top of
page |
|