<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> <html> <head> <meta name="generator" content="HTML Tidy, see www.w3.org"> <title>Configuration Options</title> </head> <body> <h3>Configuration Options</h3> <img align="left" src="pic/boom3a.gif" alt="gif"><a href= "http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, Walt Kelly</a> <p>The chicken is getting configuration advice.<br clear="left"> </p> <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 arguments. There are two classes of commands, configuration commands that configure a persistent association with a remote server or peer or reference clock, and auxilliary commands that specify environmental variables that control various related operations.</p> <h4>Configuration Commands</h4> <p>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 only those options applicable to each command are listed below. Use of options not listed may not be caught as an error, but may result in some weird and even destructive behavior.</p> <dl> <dt><tt>server <i>address</i> [key <i>key</i> | autokey] [burst] [iburst] [version <i>version</i>] [prefer] [minpoll <i>minpoll</i>] [maxpoll <i>maxpoll</i>]</tt></dt> <dt><tt>peer <i>address</i> [key <i>key</i> | autokey] [version <i> version</i>] [prefer] [minpoll <i>minpoll</i>] [maxpoll <i> maxpoll</i>]</tt></dt> <dt><tt>broadcast <i>address</i> [key <i>key</i> | autokey] [version <i>version</i>] [minpoll <i>minpoll</i>] [ttl <i> ttl</i>]</tt></dt> <dt><tt>manycastclient <i>address</i> [key <i>key</i> | autokey] [version <i>version</i>] [minpoll <i>minpoll</i> [maxpoll <i> maxpoll</i>] [ttl <i>ttl</i>]</tt></dt> <dd>These four commands specify the time server name or address to be used and the mode in which to operate. The <i>address</i> 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. <dl> <dt><tt>server</tt></dt> <dd>For type s and r addresses, this command mobilizes a persistent client mode association with the specified remote server or local radio clock. In this mode the local clock can synchronized to the remote server, but the remote server can never be synchronized to the local clock. This command should NOT be used for type <tt> b</tt> or <tt>m</tt> addresses.</dd> <dt><tt>peer</tt></dt> <dd>For type s addresses (only), this command mobilizes a persistent symmetric-active mode association with the specified remote peer. In this mode the local clock can be synchronized to the remote peer or the remote peer can be synchronized to the local clock. This is useful in a network of servers where, depending on various failure scenarios, either the local or remote peer may be the better source of time. This command should NOT be used for type <tt>b</tt>, <tt>m</tt> or <tt>r</tt> addresses.</dd> <dt><tt>broadcast</tt></dt> <dd>For type <tt>b</tt> and <tt>m</tt> addresses (only), this command mobilizes a persistent broadcast mode association. 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.</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> <dt><tt>manycastclient</tt></dt> <dd>For type <tt>m</tt> addresses (only), this command 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>The <tt>manycast</tt> command specifies that the local server is to operate in client mode with the remote servers 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> <dt>Options</dt> <dt><tt>autokey</tt></dt> <dd>All packets sent to and received from the server or peer are to include authentication fields encrypted using the autokey scheme described in the <a href="authopt.htm">Authentication Options</a> page.</dd> <dt><tt>burst</tt></dt> <dd>when the server is reachable and at each poll interval, send a burst of eight packets instead of the usual one packet. The spacing between the first and the second packets is about 16s to allow a modem call to complete, while the spacing between the remaining packets is about 2s. This is designed to improve timekeeping quality with the <tt>server</tt> command and <tt>s</tt> addresses.</dd> <dt><tt>iburst</tt></dt> <dd>When the server is unreachable and at each poll interval, send a burst of eight packets instead of the usual one. As long as the server is unreachable, the spacing between packets is about 16s to allow a modem call to complete. Once the server is reachable, the spacing between packets is about 2s. This is designed to speed the initial synchronization acquisition with the <tt>server</tt> command and <tt>s</tt> addresses and when <tt>ntpd</tt> is started with the <tt>-q</tt> option.</dd> <dt><tt>key</tt> <i><tt>key</tt></i></dt> <dd>All packets sent to and received from the server or peer are to include authentication fields encrypted using the specified <i> key</i> identifier with values from 1 to 65534, inclusive. The default is to include no encryption field.</dd> <dt><tt>minpoll <i>minpoll</i></tt><br> <tt>maxpoll <i>maxpoll</i></tt></dt> <dd>These options specify the minimum and maximum poll intervals for NTP messages, in seconds to the power of two. The maximum poll interval defaults to 10 (1,024 s), but can be increased by the <tt> maxpoll</tt> option to an upper limit of 17 (36.4 h). The minimum poll interval defaults to 6 (64 s), but can be decreased by the <tt>minpoll</tt> option to a lower limit of 4 (16 s).</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> <dt><tt>ttl <i>ttl</i></tt></dt> <dd>This option is used only with broadcast server and manycast client modes. It specifies the time-to-live <i><tt>ttl</tt></i> to use on broadcast server and multicast server and the maximum <i> <tt>ttl</tt></i> for the expanding ring search with manycast client packets. Selection of the proper value, which defaults to 127, is something of a black art and should be coordinated with the network administrator.</dd> <dt><tt>version <i>version</i></tt></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> </dl> </dd> </dl> <h4>Auxilliary Commands</h4> <dl> <dt><tt>broadcastclient</tt></dt> <dd>This command enables reception of broadcast server messages to any local interface (type b) address. Upon receiving a message for the first time, the broadcast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding broadcast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric-key or public-key authentication as described in the <a href="authopt.htm"> Authentication Options</a> page.</dd> <dt><tt>manycastserver <i>address</i> [...]</tt></dt> <dd>This command enables reception of manycast client 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. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric-key or public-key authentication as described in the <a href="authopt.htm"> Authentication Options</a> page.</dd> <dt><tt>multicastclient [<i>address</i>] [...]</tt></dt> <dd>This command enables reception of multicast server messages to the multicast group address(es) (type m) specified. Upon receiving a message for the first time, the multicast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding multicast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric-key or public-key authentication as described in the <a href= "authopt.htm">Authentication Options</a> page.</dd> </dl> <h4>Bugs</h4> <p>The syntax checking is not picky; some combinations of ridiculous and even hilarious options and modes may not be detected.</p> <hr> <a href="index.htm"><img align="left" src="pic/home.gif" alt= "gif"></a> <address><a href="mailto:mills@udel.edu">David L. Mills <mills@udel.edu></a></address> </body> </html>