- updated to 4.1.2

[packages/ntp.git] / ntpd.8

.\" -*- nroff -*"
.TH  NTPD 8 "November 17, 1999" "Version 4.0.98d" "Network Time Protocol Daemon"
.SH NAME
ntpd \- Network Time Protocol (NTP) daemon.
.SH SYNOPSIS
.B ntpd
[ -aAbdm ]
[ -c conffile ]
[ -f driftfile ]
[ -k keyfile ]
[ -l logfile ]
[ -p pidfile ]
[ -r broadcastdelay ]
[ -s statsdir ]
[ -t key ]
[ -v variable ]
[ -V variable ]

.SH DESCRIPTION
.B ntpd
is an operating system daemon which sets and maintains the system
time-of-day in synchronism with Internet standard time servers.
.B 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.
.B
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.
.PP
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.
.PP
Ordinarily,
.B 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.
.PP
If NetInfo support is built into
.B ntpd
then
.B 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.
.PP
Various internal
.B ntpd
variables can be displayed and configuration
options altered while the daemon is running using the
.B ntpq
and
.B ntpd
utility programs.
.PP
When
.B ntpd
starts it looks at the value of umask, and if it is zero
.B ntpd
will set the umask to 0222.
.SH OPTIONS
.TP
.I -a
Enable authentication mode (default).
.I -A
.TP
Disable authentication mode.
.TP
.I -b
Synchronize using NTP broadcast messages.
.TP
.I -c conffile
Specify the name and path of the configuration file.
.TP
.I -d
Specify debugging mode.  This flag may occur multiple times, with each
occurrence indicating greater detail of display.
.TP
.I -D level
Specify debugging level directly.
.TP
.I -f driftfile
Specify the name and path of the drift file.
.TP
.I -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.
.TP
.I -k keyfile
Specify the name and path of the file containing the NTP authentication
keys.
.TP
.I -l logfile
Specify the name and path of the log file.  The default is the system
log facility.
.TP
.I -m
Synchronize using NTP multicast messages on the IP multicast group
address 224.0.1.1 (requires multicast kernel).
.TP
.I -p pidfile
Specify the name and path to record the daemon's process ID.
.TP
.I -P
Override the priority limit set by the operating system.  Not
recommended for sissies.
.TP
.I -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.
.TP
.I -s statsdir
Specify the directory path for files created by the statistics
facility.
.TP
.I -t key
Add a key number to the trusted key list.
.T
.I -v variable
.TP
.I -V variable
Add a system variable listed by default.
.TP
.I -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.
.SH  THE CONFIGURATION FILE
The
.B 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 [ ...  ].
.PP
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.
.PP
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.
.TP
.I  peer address
[autokey | key key]
[burst]
[version version]
[prefer]
[minpoll minpoll]
[maxpoll maxpoll]
.PP
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.
.PP
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.
.TP
.I server address
[autokey | key key]
[burst]
[version version]
[prefer]
[minpoll minpoll]
[maxpoll maxpoll]
.PP
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.
.TP
.I broadcast address
[autokey | key key]
[burst]
[version version]
[minpoll minpoll]
[maxpoll maxpoll]
[ttl ttl]
.PP
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.
.PP
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.
.TP
.I manycastclient address
[autokey | key key]
[burst]
[version version]
[minpoll minpoll]
[maxpoll maxpoll]
[ttl ttl]
.PP
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
.PP
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
.PP
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
.TP
.I autokey
All packets sent to the address are to include authentication field
encrypted using the autokey scheme.
.TP
.I burst
At each poll interval, send a burst of eight packets spaced, instead of
the usual one.
.TP
.I 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.
.TP
.I version version
Specifies the version number to be used for outgoing NTP packets.
Versions 1-4 are the choices, with version 4 the default.
.TP
.I 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
.TP
.I 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.
.TP
.I 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.
.TP
.I 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.
.TP
.I 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.
.TP
.I 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.
.PP
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.
.TP
.I 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.
.TP
.I 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.
.TP
.I 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.
.TP
.I enable [auth | bclient | kernel | monitor | ntp | stats]
.TP
.I 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.
.TP
.I 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.
.TP
.I bclient
When enabled, this is identical to the broadcastclient command.  The
default for this flag is disable.
.TP
.I 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.
.TP
.I monitor
Enables the monitoring facility.  See the ntpdc program and the monlist
command or further information.  The default for this flag is enable.
.TP
.I 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.
.TP
.I stats
Enables the statistics facility.  The default for this flag is enable.
.SH FILES
.TP
.I /etc/ntp.conf
- the default name of the configuration file
.TP
.I /etc/ntp.drift
- the default name of the drift file
.TP
.I /etc/ntp.key
- the default name of the key file
.SH BUGS
.B 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.
.SH AUTHOR
David L.  Mills <mills@udel.edu>. Manpage abstracted from the
html documentation by Peter Breuer <ptb@it.uc3m.es>.