diff options
Diffstat (limited to 'contrib/ntp/html/confopt.htm')
| -rw-r--r-- | contrib/ntp/html/confopt.htm | 563 |
1 files changed, 245 insertions, 318 deletions
diff --git a/contrib/ntp/html/confopt.htm b/contrib/ntp/html/confopt.htm index 68ddf7fa30e8..8f911ef98059 100644 --- a/contrib/ntp/html/confopt.htm +++ b/contrib/ntp/html/confopt.htm @@ -1,330 +1,257 @@ -<html><head><title> -Configuration Options -</title></head><body><h3> -Configuration Options -</h3><hr> +<!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 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> +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>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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </dd> - </dl> - </dd> - <dd>Options</dd> - <dd> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </dd> - </dl> - </dd> +<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> - David L. Mills (mills@udel.edu) -</address> +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> </body> </html> + |