NAME
ntpd - Network Time Protocol (NTP) daemon.
SYNOPSIS
ntpd [ -aAbdDgLmnNqx ] [ -c conffile ] [ -f driftfile ] [ -i jaildir ]
[ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -P priority ] [ -r
broadcastdelay ] [ -s statsdir ] [ -t key ] [ -u user[:group] ] [ -v
variable ] [ -V variable ]
DESCRIPTION
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 neces‐
sary 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 config‐
ure 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 configura‐
tion entirely on the command line, obviating the need for a configura‐
tion 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.
OPTIONS
-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.
-i jaildir
Chroot the server to the directory jaildir. This option also
implies that the server attempts to drop root privileges at
startup (otherwise, chroot gives very little additional secu‐
rity), and it is only available if the OS supports to run the
server without full root privileges. You may need to also spec‐
ify a -u option.
-k keyfile
Specify the name and path of the file containing the NTP authen‐
tication keys.
-l logfile
Specify the name and path of the log file. The default is the
system log facility.
-L Do not listen to virtual IPs. The default is to listen.
-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.
-N To the extent permitted by the operating system, run the ntpd at
the highest priority.
-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.
-q Exit the ntpd just after the first time the clock is set. This
behavior mimics that of the ntpdate program, which is to be
retired. The -g and -x options can be used with this option.
Note: The kernel time discipline is disabled with this option.
-r broadcastdelay
Specify the default propagation delay from the broadcast/multi‐
cast 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.
-u user[:group]
Specify a user, and optionally a group, to switch to.
-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 CONFIGURATION FILE
The ntpd configuration file is read at initial startup in order to
specify the synchronization sources, modes and other related informa‐
tion. 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 fol‐
lowed 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 com‐
mands, 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 sym‐
metric 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 com‐
mand 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 associa‐
tion, 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 mul‐
ticast 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 asso‐
ciation for the multicast address specified. In this case specific
address must be supplied which matches the address used on th manycast‐
server command for the designated manycast servers. The NT multicast
address 224.0.1.1 assigned by the IANA should NOT be used unless spe‐
cific 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 specifi‐
cally 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 pack‐
ets. 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 cor‐
rectly 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. Sup‐
port 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 fre‐
quency 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 sub‐
side.
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 pro‐
gram.
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 rou‐
tine 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 dis‐
abled 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-indica‐
tors. The default for this flag is enable.
stats Enables the statistics facility. The default for this flag is
enable.
FILES
/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
BUGS
Ntpd has gotten rather fat. While not huge, it has gotten larger than
might be desirable for an elevated-priority daemon running on a work‐
station, 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.
AUTHOR
David L. Mills <mills@udel.edu>. Manpage abstracted from the html doc‐
umentation by Peter Breuer <ptb@it.uc3m.es>.
