Configuration Options

Configuration Support

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.

Configuration Commands

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 some options are not supported by all these commands while autokey and burst modes are supported by these commands, their effect in some weird mode combinations can be meaningless or even destructive.

peer address [key key | autokey | publickey keyfile] [burst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll]

server address [key key | autokey | publickey keyfile] [burst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll] [publickey keyfile]

broadcast address [key key | autokey] [burst] [version version] [minpoll minpoll] [maxpoll maxpoll] [ttl ttl]

manycastclient address [key key | autokey | publickey keyfile] [burst] [version version] [minpoll minpoll [maxpoll maxpoll] [ttl ttl] [publickey file]

These four commands specify the time server name or address to be used and the mode in which to operate. The address can be either a DNS name or a IP address in dotted-quad notation. Additional information on association behavior can be found in the Association Management page.

server

For type s and r addresses, this operates as the NTPv3 server command, which mobilizes a persistent client mode association. The server 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.

peer

For type s addresses (only), this operates as the current peer 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.

The peer 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.

broadcast

For type b and m addresses (only), this operates as the current NTPv3 broadcast 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.

In broadcast mode, the local server sends periodic broadcast messages to a client population at the address 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 broadcastclient or multicastclient commands below.

manycastclient

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 manycastserver 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.

The manycast 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 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.

Options

autokey

All packets sent to and received from the server or peer are to include authentication fields encrypted using the autokey scheme described in the Authentication Options page.

burst

At each poll interval, send a burst of eight packets spaced, instead of the usual one.

key key

All packets sent to and received from the server or peer are to include authentication fields encrypted using the specified key identifier with values from 1 to 65534, inclusive. The default is to include no encryption field.

minpoll minpoll
maxpoll maxpoll

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.

prefer

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 Mitigation Rules and the prefer Keyword page for further information.

publickey file

This command requires the NTP daemon build process be configured with the RSA library. The command specifies the name of the public key file for the server or peer. The default name for this file is ntpkey_host, where host is the DNS canonical name of the server or peer. See the Authentication Options page for further information.

ttl ttl

This option is used only with broadcast mode. It specifies the time-to-live ttl 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.

version version

Specifies the version number to be used for outgoing NTP packets. Versions 1-4 are the choices, with version 4 the default.

Auxilliary Commands

broadcastclient

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.

manycastserver 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 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.

multicastclient [address] [...]

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 broadcastclient command, but uses IP multicasting. Support for this command requires multicast kernel support.

Bugs

The syntax checking is not picky; some combinations of ridiculous and even hilarious options and modes may not be detected.

---