ntpd - Network Time Protocol (NTP) daemon.

ntpd [ -aAbdmn ] [ -c conffile ] [ -f driftfile ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -r broadcastdelay ] [ -s statsdir ] [ -t key ] [ -v variable ] [ -V variable ]

ntpd is an operating system daemon which sets and maintains the system time-of-day in synchronism with Internet standard time servers. Ntpd is a complete implementation of the Network Time Protocol (NTP) version 4 but also retains compatibility with version 3, as defined by RFC-1305 and version 1 and 2, as defined by RFC-1059 and RFC-1119, respectively. ntpd does most computations in 64-bit floating point arithmetic and does relatively clumsy 64-bit fixed point operations only when necessary to preserve the ultimate precision, about 232 picoseconds. While the ultimate precision, is not achievable with ordinary workstations and networks of today, it may be required with future nanosecond CPU clocks and gigabit LANs.

The daemon can operate in any of several modes, including symmetric active/passive, client/server broadcast/multicast and manycast. A broadcast/multicast or manycast client can discover remote servers, compute server-client propagation delay correction factors and configure itself automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment.

Ordinarily, ntpd reads the ntp.conf configuration file at startup time in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited configuration entirely on the command line, obviating the need for a configuration file. This may be particularly appropriate when the local host is to be configured as a broadcast/multicast client or manycast client, with all peers being determined by listening to broadcasts at run time.

If NetInfo support is built into ntpd then ntpd will attempt to read its configuration from the NetInfo if the default ntp.conf file cannot be read and no file is specified by the -c option.

Various internal ntpd variables can be displayed and configuration options altered while the daemon is running using the ntpq and ntpd utility programs.

When ntpd starts it looks at the value of umask, and if it is zero ntpd will set the umask to 0222.

-a

Enable authentication mode (default). -A

Disable authentication mode.

-b

Synchronize using NTP broadcast messages.

-c conffile

Specify the name and path of the configuration file.

-d

Specify debugging mode. This flag may occur multiple times, with each occurrence indicating greater detail of display.

-D level

Specify debugging level directly.

-f driftfile

Specify the name and path of the drift file.

-g

Normally, the daemon exits if the offset exceeds a 1000s sanity limit This option overrides this limit and allows the time to be set to an value without restriction.

-k keyfile

Specify the name and path of the file containing the NTP authentication keys.

-l logfile

Specify the name and path of the log file. The default is the system log facility.

-m

Synchronize using NTP multicast messages on the IP multicast group address 224.0.1.1 (requires multicast kernel).

-n

Don't fork, i.e. run in the foreground.

-p pidfile

Specify the name and path to record the daemon's process ID.

-P

Override the priority limit set by the operating system. Not recommended for sissies.

-r broadcastdelay

Specify the default propagation delay from the broadcast/multicast server and this computer. This is necessary only if the delay cannot be computed automatically by the protocol.

-s statsdir

Specify the directory path for files created by the statistics facility.

-t key

Add a key number to the trusted key list. -v variable

-V variable

Add a system variable listed by default.

-x

Ordinarily, if the time is to be adjusted more than 128 ms, it is stepped, not gradually slewed. This option forces the time to be slewed in all cases. Note: Since the slew rate is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. Thus an adjustment of many seconds can take hours or days to amortize.

The ntpd configuration file is read at initial startup in order to specify the synchronization sources, modes and other related information. Usually, it is installed in the /etc directory, but could be installed elsewhere (see the -c conffile command line option). The file format is similar to other Unix configuration files - comments begin with a # character and extend to the end of the line; blank lines are ignored. Configuration commands consist of an initial keyword followed by a list of arguments, some of which may be optionally separated by whitespace. Commands may not be continued over multiple lines. Arguments may be host names, host addresses written in numeric dotted-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by [ ] in the following descriptions, while alternatives are separated by |. The notation [ ... ] means an optional, indefinite repetition of the last item before the [ ... ].

While there is a rich set of options available, the only required option is one or more of the server, peer, broadcast or manycastclient commands.

Following is a description of the NTPv4 configuration commands. 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.

peer address

[autokey | key key] [burst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll]

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.

server address

[autokey | key key] [burst] [version version] [prefer] [minpoll minpoll] [maxpoll maxpoll]

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.

broadcast address

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

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 interface (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 address

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

For type m addresses (only), this mobilizes a manycast client-mod association for the multicast address specified. In this case specific address must be supplied which matches the address used on th manycastserver command for the designated manycast servers. The NT 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 th Internet with these messages and causing a possibly massive implosion o replies at the sender

The manycast command specifies that the local server is to operate i client mode with the remote server that are discovered as the result o broadcast/multicast messages. The client broadcasts a request message to the group address associated with the specified address an 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

These four commands specify the time server name or address to be use 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 behaviour can be found in the Association Management page

autokey

All packets sent to the address are to include authentication field encrypted using the autokey scheme.

burst

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

key key

All packets sent to the address are to include authentication field encrypted using the specified key identifier, which is an unsigned 32-bit integer less than 65536. The default is to include no encryption field.

version version

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

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

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.

minpoll minpoll maxpoll maxpoll

These options specify the minimum and maximum polling intervals for NTP messages. The values are interpreted as dual logarithms (2 ^ x). The default range is 6 (2^6 = 64 s) to 10 (2^10 = 1024 s). The allowable range is 4 (16 s) to 17 (36.4 h).

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

multicastclient

[address] [...] This command directs the local server to listen for multicast messages at the group address(es) of these global network. The default address is that assigned by the Number 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 a multicast kernel.

driftfile driftfile

This command specifies the name of the file use 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 assume zero. In this case, it may take some hours for the frequency to stabilize and the residual timing errors to subside.

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 ntpd must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should be avoided.

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 possible massive implosion at the original sender.

revoke [logsec]

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.

autokey [logsec]

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.

enable [auth | bclient | kernel | monitor | ntp | stats]

disable [auth | bclient | kernel | monitor | ntp | stats]

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 ntpdc utility program.

auth

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.

bclient

When enabled, this is identical to the broadcastclient command. The default for this flag is disable.

kernel

Enables the precision-time kernel support for the ntp_adjtime() 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.

monitor

Enables the monitoring facility. See the ntpdc program and the monlist command or further information. The default for this flag is enable.

ntp

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. The default for this flag is enable.

stats

Enables the statistics facility. The default for this flag is enable.

/etc/ntp.conf

- the default name of the configuration file

/etc/ntp.drift

- the default name of the drift file

/etc/ntp.key

- the default name of the key file

Ntpd has gotten rather fat. While not huge, it has gotten larger than might be desirable for an elevated-priority daemon running on a workstation, particularly since many of the fancy features which consume the space were designed more with a busy primary server, rather than a high stratum workstation, in mind.

David L. Mills <mills@udel.edu>. Manpage abstracted from the html documentation by Peter Breuer <ptb@it.uc3m.es>.