NetBSD/dist/ntp/html/confopt.htm

331 lines
17 KiB
HTML

<html><head><title>
Configuration Options
</title></head><body><h3>
Configuration Options
</h3><hr>
<h4>Configuration Support</h4>
<p>Following is a description of the configuration commands in
NTPv4. These commands have the same basic functions as in NTPv3
and in some cases new functions and new operands. The various
modes are determined by the command keyword and the type of the
required IP address. Addresses are classed by type as (s) a
remote server or peer (IP class A, B and C), (b) the broadcast
address of a local interface, (m) a multicast address (IP class
D), or (r) a reference clock address (127.127.x.x). Note that,
while autokey and burst modes are supported by these commands,
their effect in some weird mode combinations can be meaningless
or even destructive.</p>
<dl>
<dt><tt>peer </tt><i><tt>address</tt></i><tt> [autokey | key </tt><i><tt>key</tt></i><tt>]
[burst] [version </tt><i><tt>version</tt></i><tt>]
[prefer] [minpoll </tt><i><tt>minpoll</tt></i><tt>]</tt><i><tt>
</tt></i><tt>[maxpoll </tt><i><tt>maxpoll</tt></i><tt>]</tt></dt>
<dd>&nbsp;</dd>
<dt><tt>server </tt><i><tt>address</tt></i><tt> [autokey |
key </tt><i><tt>key</tt></i><tt>] [burst] [version </tt><i><tt>version</tt></i><tt>]
[prefer] [minpoll </tt><i><tt>minpoll</tt></i><tt>]</tt><i><tt>
</tt></i><tt>[maxpoll </tt><i><tt>maxpoll</tt></i><tt>]</tt></dt>
<dd>&nbsp;</dd>
<dt><tt>broadcast </tt><i><tt>address</tt></i><tt> [autokey |
key </tt><i><tt>key</tt></i><tt>] [burst] [version </tt><i><tt>version</tt></i><tt>]
[minpoll </tt><i><tt>minpoll</tt></i><tt>]</tt><i><tt> </tt></i><tt>[maxpoll
</tt><i><tt>maxpoll</tt></i><tt>] [ttl </tt><i><tt>ttl</tt></i><tt>]</tt></dt>
<dd>&nbsp;</dd>
<dt><tt>manycastclient </tt><i><tt>address</tt></i><tt>
[autokey | key </tt><i><tt>key</tt></i><tt>] [burst]
[version </tt><i><tt>version</tt></i><tt>] [minpoll </tt><i><tt>minpoll
</tt></i><tt>[maxpoll </tt><i><tt>maxpoll</tt></i><tt>]
[ttl </tt><i><tt>ttl</tt></i><tt>]</tt></dt>
<dd>&nbsp;</dd>
<dd>These four commands specify the time server name or
address to be used and the mode in which to operate. The <i><tt>address</tt></i><tt>
</tt>can be either a DNS name or a IP address in
dotted-quad notation. Additional information on
association behavior can be found in the <a
href="assoc.htm">Association Management</a> page.</dd>
<dd>&nbsp;</dd>
<dd><dl>
<dt><tt>server</tt></dt>
<dd>For type s and r addresses, this operates as the
NTPv3 server command, which mobilizes a
persistent client mode association. The <tt>server</tt>
command specifies that the local server is to
operate in client mode with the specified remote
server. 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.</dd>
<dd>&nbsp;</dd>
<dt><tt>peer</tt></dt>
<dd>For type s addresses (only), this operates as the
current <tt>peer </tt>command, which mobilizes a
persistent symmetric-active mode association,
except that additional modes are available. This
command should NOT be used for type b, m or r
addresses.</dd>
<dd>&nbsp;</dd>
<dd>The <tt>peer</tt> command specifies that the
local server is to operate in symmetric active
mode with the remote server. 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 may be the better source of time.</dd>
<dd>&nbsp;</dd>
<dt><tt>broadcast</tt></dt>
<dd>For type b and m addresses (only), this is
operates as the current NTPv3 <tt>broadcast </tt>command,
which mobilizes a persistent broadcast mode
association, except that additional modes are
available. Multiple commands can be used to
specify multiple local broadcast interfaces
(subnets) and/or multiple multicast groups. Note
that local broadcast messages go only to the
interface associated with the subnet specified,
but multicast messages go to all interfaces. In
the current implementation, the source address
used for these messages is the Unix host default
address.</dd>
<dd>&nbsp;</dd>
<dd>In broadcast mode, the local server sends
periodic broadcast messages to a client
population at the <i><tt>address </tt></i>specified,
which is usually the broadcast address on (one
of) the local network(s) or a multicast address
assigned to NTP. The IANA has assigned the
multicast group address 224.0.1.1 exclusively to
NTP, but other nonconflicting addresses can be
used to contain the messages within
administrative boundaries.. Ordinarily, this
specification applies only to the local server
operating as a sender; for operation as a
broadcast client, see the <tt>broadcastclient</tt>
or <tt>multicastclient</tt> commands below.</dd>
<dd>&nbsp;</dd>
<dt><tt>manycastclient</tt> </dt>
<dd>For type m addresses (only), this mobilizes a
manycast client-mode association for the
multicast address specified. In this case a
specific address must be supplied which matches
the address used on the <tt>manycastserver </tt>command
for the designated manycast servers. The NTP
multicast address 224.0.1.1 assigned by the IANA
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. </dd>
<dd>&nbsp;</dd>
<dd>The <tt>manycast </tt>command specifies that the
local server is to operate in client mode with
the remote server that are discovered as the
result of broadcast/multicast messages. The
client broadcasts a request message to the group
address associated with the specified <i><tt>address
</tt></i>and specifically enabled servers respond
to these messages. The client selects the servers
providing the best time and continues as with the
<tt>server </tt>command. The remaining servers
are discarded as if never heard.</dd>
<dd>&nbsp;</dd>
</dl>
</dd>
<dd>Options</dd>
<dd>&nbsp;</dd>
<dd><dl>
<dt><tt>autokey</tt></dt>
<dd>All packets sent to the address are to include
authentication fields encrypted using the autokey
scheme.</dd>
<dd>&nbsp;</dd>
<dt><tt>burst</tt></dt>
<dd>At each poll interval, send a burst of eight
packets spaced, instead of the usual one.</dd>
<dd>&nbsp;</dd>
<dt><tt>key </tt><i><tt>key</tt></i></dt>
<dd>All packets sent to the address are to include
authentication fields encrypted using the
specified <i>key</i> identifier, which is an
unsigned 32-bit integer less than 65536. The
default is to include no encryption field.</dd>
<dd>&nbsp;</dd>
<dt><tt>version </tt><i><tt>version</tt></i></dt>
<dd>Specifies the version number to be used for
outgoing NTP packets. Versions 1-4 are the
choices, with version 4 the default.</dd>
<dd>&nbsp;</dd>
<dt><tt>prefer</tt></dt>
<dd>Marks the server as preferred. All other things
being equal, this host will be chosen for
synchronization among a set of correctly
operating hosts. See the <a href="prefer.htm">Mitigation
Rules and the <tt>prefer</tt> Keyword </a>page
for further information.</dd>
<dd>&nbsp;</dd>
<dt><tt>ttl </tt><i><tt>ttl</tt></i></dt>
<dd>This option is used only with broadcast mode. It
specifies the time-to-live <i><tt>ttl</tt></i> to
use on multicast packets. Selection of the proper
value, which defaults to 127, is something of a
black art and must be coordinated with the
network administrator.</dd>
<dd>&nbsp;</dd>
<dt><tt>minpoll </tt><i><tt>minpoll</tt></i></dt>
<dt><tt>maxpoll </tt><i><tt>maxpoll</tt></i></dt>
<dd>These options specify the minimum and maximum
polling intervals for NTP messages, in seconds to
the power of two. The default range is 6 (64 s)
to 10 (1,024 s).The allowable range is 4 (16 s)
to 17 (36.4 h) inclusive.</dd>
<dd>&nbsp;</dd>
</dl>
</dd>
<dt><tt>broadcastclient</tt></dt>
<dd>This command directs the local server to listen for and
respond to broadcast messages received on any local
interface. 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 should operate using authentication and
the same trusted key and key identifier.</dd>
<dd>&nbsp;</dd>
<dt><tt>multicastclient [</tt><i><tt>address</tt></i><tt>]
[...]</tt></dt>
<dd>This command directs the local server to listen for
multicast messages at the group address(es) of the global
network. The default address is that assigned by the
Numbers Czar to NTP (224.0.1.1). This command operates in
the same way as the <tt>broadcastclient</tt> command, but
uses IP multicasting. Support for this command requires a
multicast kernel.</dd>
<dd>&nbsp;</dd>
<dt><tt>driftfile </tt><i><tt>driftfile</tt></i></dt>
<dd>This command specifies the name of the file used to
record the frequency offset of the local clock
oscillator. If the file exists, it is read at startup in
order to set the initial frequency offset and then
updated once per hour with the current frequency offset
computed by the daemon. 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.</dd>
<dd>&nbsp;</dd>
<dd>The file format consists of a single line containing a
single floating point number, which records the frequency
offset measured in parts-per-million (PPM). The file is
updated by first writing the current drift value into a
temporary file and then renaming this file to replace the
old version. This implies that <tt>ntpd</tt> must have
write permission for the directory the drift file is
located in, and that file system links, symbolic or
otherwise, should be avoided.</dd>
<dd>&nbsp;</dd>
<dt><tt>manycastserver </tt><i><tt>address </tt></i><tt>[...]</tt></dt>
<dd>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 to the multicast group
address(es) (type m) specified. At least one address is
required, but The NTP multicast address 224.0.1.1
assigned by the IANA 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.</dd>
<dd>&nbsp;</dd>
<dt><tt>revoke [</tt><i><tt>logsec</tt></i><tt>]</tt> </dt>
<dd>Specifies the interval between recomputations of the
private value used with the autokey feature, which
ordinarily requires an expensive public- key computation.
The default value is 12 (65,536 s or about 18 hours). For
poll intervals above the specified interval, a new
private value will be recomputed for every message sent.</dd>
<dd>&nbsp;</dd>
<dt><tt>autokey [</tt><i><tt>logsec</tt></i><tt>]</tt> </dt>
<dd>Specifies the interval between regenerations of the
session key list used with the autokey feature. Note that
the size of the key list for each association depends on
this interval and the current poll interval. The default
value is 12 (4096 s or about 1.1 hours). For poll
intervals above the specified interval, a session key
list with a single entry will be regenerated for every
message sent.</dd>
<dd>&nbsp;</dd>
<dt><tt>enable [auth | bclient | kernel | monitor | ntp |
stats]</tt></dt>
<dt><tt>disable [auth | bclient | kernel | monitor | ntp |
stats</tt><font face="Courier New">] </font></dt>
<dd>Provides a way to enable or disable various server
options. Flags not mentioned are unaffected. Note that
all of these flags can be controlled remotely using the <a
href="ntpdc.htm"><tt>ntpdc</tt></a> utility program.</dd>
<dd>&nbsp;</dd>
<dd><dl>
<dt><tt>auth</tt></dt>
<dd>Enables 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
enable.</dd>
<dd>&nbsp;</dd>
<dt><tt>bclient</tt></dt>
<dd>When enabled, this is identical to the <tt>broadcastclient</tt>
command. The default for this flag is disable.</dd>
<dd>&nbsp;</dd>
<dt><tt>kernel</tt></dt>
<dd>Enables the precision-time kernel support for the
<tt>ntp_adjtime()</tt> system call, if
implemented. Ordinarily, support for this routine
is detected automatically when the NTP daemon is
compiled, so it is not necessary for the user to
worry about this flag. It flag is provided
primarily so that this support can be disabled
during kernel development.</dd>
<dd>&nbsp;</dd>
<dt><tt>monitor</tt></dt>
<dd>Enables the monitoring facility. See the <tt>ntpdc</tt>
program and the <tt>monlist</tt> command or
further information. The default for this flag is
enable.</dd>
<dd>&nbsp;</dd>
<dt><tt>ntp</tt></dt>
<dd>Enables the server to adjust its local clock by
means of NTP. If disabled, 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. In this case,
the local clock driver can be used to provide
this function and also certain time variables for
error estimates and leap-indicators. See the <a
href="refclock.htm">Reference Clock Drivers </a>page
for further information. The default for this
flag is enable.</dd>
<dd>&nbsp;</dd>
<dt><tt>stats</tt></dt>
<dd>Enables the statistics facility. See the <a
href="monopt.htm">Monitoring Options </a>page for
further information. The default for this flag is
enable.</dd>
<dd>&nbsp;</dd>
</dl>
</dd>
</dl>
<hr>
<address>
David L. Mills (mills@udel.edu)
</address>
</body>
</html>