diff options
Diffstat (limited to 'html/confopt.html')
| -rw-r--r-- | html/confopt.html | 272 |
1 files changed, 194 insertions, 78 deletions
diff --git a/html/confopt.html b/html/confopt.html index e2a04c47cd66..05847c2ee59b 100644 --- a/html/confopt.html +++ b/html/confopt.html @@ -1,82 +1,198 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - <html> - - <head> - <meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <title>Server Options</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Server Options</h3> - <img src="pic/boom3a.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a> - <p>The chicken is getting configuration advice.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:57</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="270">Monday, October 10, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#cfg">Configuration Commands</a> - <li class="inline"><a href="#opt">Command Options</a> - <li class="inline"><a href="#aux">Auxilliary Commands</a> - <li class="inline"><a href="#bug">Bugs</a> - </ul> - <hr> - <p>Following is a description of the configuration commands in NTPv4. There are two classes of commands, configuration commands that configure an association with a remote server, peer or reference clock, and auxilliary commands that specify environmental variables that control various related operations.</p> - <h4 id="cfg">Configuration Commands</h4> - <p>The various modes are determined by the command keyword and the required IP address. Addresses are classed by type as (s) a remote server or peer (IPv4 class A, B and C), (b) the broadcast address of a local interface, (m) a multicast address (IPv4 class D), or (r) a reference clock address (127.127.x.x). The options that can be used with these commands are listed below.</p> - <p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is detected, support for the IPv6 address family is generated in addition to the default support of the IPv4 address family. IPv6 addresses can be identified by the presence of colons ":" in the address field. IPv6 addresses can be used almost everywhere where IPv4 addresses can be used, with the exception of reference clock addresses, which are always IPv4. Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p> - <p>There are three types of associations: persistent, preemptable and ephemeral. Persistent associations are mobilized by a configuration command and never demobilized. Preemptable associations, which are new to NTPv4, are mobilized by a configuration command which includes the <tt>prempt</tt> flag and are demobilized by timeout or error. Ephemeral associations are mobilized upon arrival of designated messages and demobilized by timeout or error.</p> +<head> +<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Server Options</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<h3>Server Options</h3> +<img src="pic/boom3a.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, +Walt Kelly</a> +<p>The chicken is getting configuration advice.</p> +<p>Last update: + <!-- #BeginDate format:En2m -->25-Nov-2009 4:46<!-- #EndDate --> +</p> +<br clear="left"> +<h4>Related Links</h4> +<script type="text/javascript" language="javascript" src="scripts/command.txt"></script> +<script type="text/javascript" language="javascript" src="scripts/confopt.txt"></script> +<h4>Table of Contents</h4> +<ul> + <li class="inline"><a href="#cfg">Configuration Commands</a></li> + <li class="inline"><a href="#opt">Command Options</a></li> + <li class="inline"><a href="#aux">Auxilliary Commands</a></li> + <li class="inline"><a href="#bug">Bugs</a></li> +</ul> +<hr> +<p>Following is a description of the configuration commands in NTPv4. There are + two classes of commands, configuration commands that configure an association + with a remote server, peer or reference clock, and auxilliary commands that + specify environmental variables that control various related operations. </p> +<p>The various modes described on the <a href="assoc.html">Association Management</a> page + are determined by the command keyword and the DNS name or IP address. Addresses + are classed by type as (s) a remote server or peer (IPv4 class A, B and C), + (b) the IP broadcast address of a local interface, (m) a multicast address (IPv4 + class D), or (r) a reference clock address (127.127.x.x). For type m addresses + the IANA has assigned the multicast group address IPv4 224.0.1.1 and IPv6 ff05::101 + (site local) exclusively to NTP, but other nonconflicting addresses can be used. </p> +<p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is detected, + support for the IPv6 address family is generated in addition to the default + IPv4 address family. IPv6 addresses can be identified by the presence of colons ":" in + the address field. IPv6 addresses can be used almost everywhere where IPv4 addresses + can be used, with the exception of reference clock addresses, which are always + IPv4. Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier + preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier + forces DNS resolution to the IPv6 namespace.</p> +<h4 id="cfg">Configuration Commands</h4> +<dl> + <dt id="server"><tt>server <i>address</i> [options ...]</tt><br> + <tt>peer <i>address</i> [options ...]</tt><br> + <tt>broadcast <i>address</i> [options ...]</tt><br> + <tt>manycastclient <i>address</i> [options ...]</tt><br> + <tt>pool <i>address</i> [options ...]</tt><br> + <tt>unpeer [<i>address</i> | <i>associd</i>]</tt></dt> + <dd>These 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 + IPv4 or IPv6 address in standard notation. In general, multiple commands of + each type can be used for different server and peer addresses or multicast + groups. <dl> - <dt><tt>server <i>address</i> [options ...]</tt><br> - <tt>peer <i>address</i> [</tt><tt>options ...]<br> - broadcast <i>address</i> [options ...]</tt><br> - <tt>manycastclient <i>address</i> [options ...]</tt> - <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.html">Association Management</a> page. - <dl> - <dt><tt>server</tt> - <dd>For type s and r addresses (only), this command normally mobilizes a persistent client mode association with the specified remote server or local reference clock. If the <tt>preempt</tt> flag is specified, a preemptable association is mobilized instead. In client mode the client clock can synchronize to the remote server or local reference clock, but the remote server can never be synchronized to the client clock. This command should NOT be used for type <tt>b</tt> or <tt>m</tt> addresses. <dt><tt>peer</tt> - <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. - <dt><tt>broadcast</tt> - <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>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 IPv4 224.0.1.1 and IPv6 ff05::101 (site local) 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. - <dt><tt>manycastclient</tt> - <dd>For type <tt>m</tt> addresses (only), this command mobilizes a preemptable manycast client mode association for the multicast group address specified. In this mode 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>The <tt>manycastclient</tt> command specifies that the host 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. - </dl> - </dl> - <h4 id="opt">Command Options</h4> - <dl> - <dt><tt>autokey</tt> - <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.html">Authentication Options</a> page. This option is valid with all commands.<dt><tt>burst</tt> - <dd>When the server is reachable, send a burst of eight packets instead of the usual one. The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the <a href="miscopt.html"><tt>calldelay</tt></a> command to allow additional time for a modem or ISDN call to complete. This option is valid with only the <tt>server</tt> command and is a recommended option with this command when the <tt>maxpoll</tt> option is 11 or greater. <dt><tt>iburst</tt> - <dd>When the server is unreachable, send a burst of eight packets instead of the usual one. The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the <a href="miscopt.html"><tt>calldelay</tt></a> command to allow additional time for a modem or ISDN call to complete. This option is valid with only the <tt>server</tt> command and is a recommended option with this command.<dt><tt>key</tt> <i><tt>key</tt></i> - <dd>All packets sent to and received from the server or peer are to include authentication fields encrypted using the specified <i><tt>key</tt></i> identifier with values from 1 to 65534, inclusive. The default is to include no encryption field. This option is valid with all commands.<dt><tt>minpoll <i>minpoll</i></tt><br> - <tt>maxpoll <i>maxpoll</i></tt> - <dd>These options specify the minimum and maximum poll intervals for NTP messages, in seconds as a 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). These option are valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>noselect</tt> - <dd>Marks the server as unused, except for display purposes. The server is discarded by the selection algorithm. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>preempt</tt> - <dd>Specifies the association as preemptable rather than the default persistent. This option is valied only with the <tt>server</tt> command.<dt><tt>prefer</tt> - <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.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page for further information. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>true</tt> - <dd>Force the association to assume truechimer status; that is, always survive the selection and clustering algorithms. This option can be used with any association, but is most useful for reference clocks with large jitter on the serial port and precision pulse-per-second (PPS) signals. Caution: this option defeats the algorithms designed to cast out falsetickers and can allow these sources to set the system clock. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>ttl <i>ttl</i></tt> - <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. - <dt><tt>version <i>version</i></tt> - <dd>Specifies the version number to be used for outgoing NTP packets. Versions 1-4 are the choices, with version 4 the default. This option is valid only with the <tt>server,</tt> <tt>peer</tt> and <tt>broadcast</tt> commands. - </dl> - <h4 id="aux">Auxilliary Commands</h4> - <dl> - <dt><tt>broadcastclient [novolley]</tt> - <dd>This command enables reception of broadcast server messages to any local interface (type <tt>b</tt>) address. Ordinarily, 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, after which it continues in listen-only mode. If the <tt>novolley</tt> keyword is present, the exchange is not used and the value specified in the <tt>broadcastdelay</tt> command is used or, if the <tt>broadcastdelay</tt> command is not used, the default 4.0 ms. 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.html">Authentication Options</a> page. Note that the <tt>novolley</tt> keyword is incompatible with public key authentication.<dt><tt>manycastserver <i>address</i> [...]</tt> - <dd>This command enables reception of manycast client messages to the multicast group address(es) (type <tt>m</tt>) specified. At least one address is required. 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.html">Authentication Options</a> page. - <dt><tt>multicastclient <i>address</i> [...]</tt> - <dd>This command enables reception of multicast server messages to the multicast group address(es) (type <tt>m</tt>) 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.html">Authentication Options</a> page. - </dl> - <h4 id="bug">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> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - + <dt><tt>server</tt></dt> + <dd>For type s and r addresses (only), this command mobilizes a persistent + client mode association with the specified remote server or local reference + clock. If the <tt>preempt</tt> flag is specified, a preemptable client mode + association is mobilized instead.</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.</dd> + <dt><tt>broadcast</tt></dt> + <dd>For type b and m addressees (only), this command mobilizes a persistent + broadcast or multicast server mode association. Note that type + b messages go only to the interface specified, but type m messages go to + all interfaces.</dd> + <dt><tt>manycastclient</tt></dt> + <dd>For type m addresses (only), this command mobilizes a manycast client + mode association for the multicast group address specified. In this mode + the address must match the address specified on the <tt>manycastserver</tt> command + of one or more designated manycast servers.</dd> + <dt><tt>pool</tt></dt> + <dd>For type s messages (only) this command mobilizes a client mode association + for servers implementing the pool automatic server discovery scheme described + on the <a href="assoc.html">Association Management</a> page. The address + is a DNS name in the form <tt><i>area</i>.pool.ntp.org</tt>, where <tt><i>area</i></tt> is + a qualifier designating the server geographic area such as <tt>us</tt> or <tt>europe</tt>.</dd> + <dt><tt>unpeer</tt></dt> + <dd>This command removes a previously configured association. An address or association ID can + be used to identify the association. Either an IP address or DNS name can be used. This + command is most useful when supplied via <tt><a href="ntpq.html">ntpq</a></tt> runtime + configuration commands <tt>:config</tt> and <tt>config-from-file</tt>.</dd> + </dl></dd> +</dl> +<h4 id="opt">Command Options</h4> +<dl> + <dt><tt>autokey</tt></dt> + <dd>Send and receive packets authenticated by the Autokey scheme described + in the <a href="authopt.html">Authentication Options</a> page. This option + is mutually exclusive with the <tt>key</tt> option.</dd> + <dt><tt>burst</tt></dt> + <dd>When the server is reachable, send a burst of eight packets instead of the + usual one. The packet spacing is normally 2 s; however, the spacing between + the first and second packets can be changed with the <a href="miscopt.html"><tt>calldelay</tt></a> command + to allow additional time for a modem or ISDN call to complete. This option + is valid only with the <tt>server</tt> command and type s addressesa. + It is a recommended option when the <tt>maxpoll</tt> option is greater than + 10 (1024 s).</dd> + <dt><tt>iburst</tt></dt> + <dd>When the server is unreachable, send a burst of eight packets instead of + the usual one. The packet spacing is normally 2 s; however, the spacing between + the first and second packets can be changed with the <a href="miscopt.html"><tt>calldelay</tt></a> command + to allow additional time for a modem or ISDN call to complete. This option + is valid only with the <tt>server</tt> command and type s addresses. It is + a recommended option with this command.</dd> + <dt><tt>key</tt> <i><tt>key</tt></i></dt> + <dd>Send and receive packets authenticated by the symmetric key scheme described + in the <a href="authopt.html">Authentication Options</a> page. + The <i><tt>key</tt></i> specifies the key identifier with values from 1 to + 65534, inclusive. This option is mutually exclusive with the <tt>autokey</tt> option.</dd> + <dt><tt>minpoll <i>minpoll<br> + </i></tt><tt>maxpoll <i>maxpoll</i></tt></dt> + <dd>These options specify the minimum and maximum poll intervals for NTP messages, + in seconds as a power of two. The maximum poll interval defaults to 10 + (1024 s), but can be increased by the <tt>maxpoll</tt> option to an upper limit + of 17 (36 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 3 (8 s).</dd> + <dt><tt>mode <i>option</i></tt></dt> + <dd>Pass the <tt><i>option</i></tt> to a reference clock driver, where <tt><i>option</i></tt> is + an integer in the range from 0 to 255, inclusive. This option is valid + only with type r addresses.</dd> + <dt><tt>noselect</tt></dt> + <dd>Marks the server or peer to be ignored by the selection algorithm but visible + to the monitoring program. This option is ignored with the <tt>broadcast</tt> command.</dd> + <dt><tt>preempt</tt></dt> + <dd>Specifies the association as preemptable rather than the default persistent. + This option is ignored with the <tt>broadcast</tt> command and is most useful + with the <tt>manycastclient</tt> and <tt>pool</tt> commands.</dd> + <dt><tt>prefer</tt></dt> + <dd>Mark 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.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page + for further information. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.</dd> + <dt><tt>true</tt></dt> + <dd>Mark the association to assume truechimer status; that is, always survive + the selection and clustering algorithms. This option can be used with any association, + but is most useful for reference clocks with large jitter on the serial port + and precision pulse-per-second (PPS) signals. Caution: this option defeats + the algorithms designed to cast out falsetickers and can allow these sources + to set the system clock. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.</dd> + <dt><tt>ttl <i>ttl</i></tt></dt> + <dd>This option specifies the time-to-live <i><tt>ttl</tt></i> for the <tt>broadcast</tt> command + and the maximum <i><tt>ttl</tt></i> for the expanding ring search used by the <tt>manycastclient</tt> command. + Selection of the proper value, which defaults to 127, is something of a black art and should be coordinated with the network administrator. This option is invalid with type r addresses.</dd> + <dt><tt>version <i>version</i></tt></dt> + <dd>Specifies the version number to be used f +or outgoing NTP packets. Versions + 1-4 are the choices, with version 4 the default.</dd> + <dt><tt>xleave</tt></dt> + <dd>Operate in interleaved mode (symmetric and broadcast modes only). (see <a href="xleave.html">NTP + Interleaved Modes</a>)</dd> +</dl> +<h4 id="aux">Auxilliary Commands</h4> +<dl> + <dt id="broadcastclient"><tt>broadcastclient</tt></dt> + <dd>Enable reception of broadcast server messages to any local interface (type + b address). Ordinarily, upon receiving a broadcast message for the first + time, the broadcast client measures the nominal server propagation delay using + a brief client/server exchange, after which it continues in listen-only mode. + If a nonzero value is specified in the <tt>broadcastdelay</tt> command, the + value becomes the delay and the volley is not executed. Note: the <tt>novolley</tt> option + has been deprecated for future enhancements. 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.html">Authentication + Options</a> page. Note that the <tt>novolley</tt> keyword is incompatible with + public key authentication.</dd> + <dt id="manycastserver"><tt>manycastserver <i>address</i> [...]</tt></dt> + <dd>Enable reception of manycast client messages (type m)to the multicast group + address(es) (type m) specified. At least one address is required. Note that, + in order to avoid accidental or malicious disruption, both the server and client + should operate using symmetric key or public key authentication as described + in the <a href="authopt.html">Authentication Options</a> page.</dd> + <dt id="multicastclient"><tt>multicastclient <i>address</i> [...]</tt></dt> + <dd>Enable 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.html">Authentication Options</a> page.</dd> +</dl> +<h4 id="bug">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> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> </html> |