NetBSD/usr.sbin/ntp/ntpd/ntpd.8

.\"	$NetBSD: ntpd.8,v 1.14 2003/06/30 10:39:28 wiz Exp $
.\" Converted from HTML to mandoc by ntp-html2mdoc.pl
.\"
.Dd February 21, 2002
.Dt NTPD 8
.Os
.Sh NAME
.Nm ntpd
.Nd Network Time Protocol (NTP) daemon
.Sh SYNOPSIS
.Nm
.Op Fl aAbdm
.Op Fl c Ar conffile
.Op Fl f Ar driftfile
.Op Fl g
.Op Fl i Ar chrootdir
.Op Fl k Ar keyfile
.Op Fl l Ar logfile
.Op Fl p Ar pidfile
.Op Fl r Ar broadcastdelay
.Op Fl s Ar statsdir
.Op Fl t Ar key
.Op Fl u Ar user[:group]
.Op Fl v Ar variable
.Op Fl V Ar variable
.Op Fl x
.Sh DESCRIPTION
.Nm
is an operating system daemon which sets and maintains the
system time-of-day in synchronism with Internet standard time servers.
.Nm
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.
.Nm
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,
.Nm
reads the
.Pa 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
.Nm ,
then
.Nm
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
.Fl c
option.
.Pp
Various internal
.Nm
variables can be displayed and
configuration options altered while the daemon is running using the
.Xr ntpq 8
and
.Xr ntpdc 8
utility programs.
.Pp
When
.Nm
starts it looks at the value of
.Pa umask
,
and if it's zero
.Nm
will set the
.Pa umask
to
.Pa 022
.
.Sh COMMAND LINE OPTIONS
.Bl -tag -width indent
.It Fl a
Enable authentication mode (default).
.It Fl A
Disable authentication mode.
.It Fl b
Synchronize using NTP broadcast messages.
.It Fl c Ar conffile
Specify the name and path of the configuration file.
.It Fl d
Specify debugging mode. This flag may occur multiple times, with
each occurrence indicating greater detail of display.
.It Fl D Ar level
Specify debugging level directly.
.It Fl f Ar driftfile
Specify the name and path of the drift file.
.It Fl g
Normally, the daemon exits if the offset exceeds a 1000-s sanity
limit. This option overrides this limit and allows the time to be set to
any value without restriction; however, this can happen only once. After
that, the daemon will exit if the limit is exceeded.
.It Fl i Ar chrootdir
Specify the path to a directory in which ntpd will run chrooted.
.It Fl k Ar keyfile
Specify the name and path of the file containing the NTP
authentication keys.
.It Fl l Ar logfile
Specify the name and path of the log file. The default is the system
log facility.
.It Fl m
Synchronize using NTP multicast messages on the IP multicast group
address 224.0.1.1 (requires multicast kernel).
.It Fl p Ar pidfile
Specify the name and path to record the daemon's process ID.
.It Fl P
Override the priority limit set by the operating system. Not
recommended for sissies.
.It Fl r Ar 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.
.It Fl s Ar statsdir
Specify the directory path for files created by the statistics
facility.
.It Fl t Ar key
Add a key number to the trusted key list.
.It Fl u Ar user[:group]
Specify user (and optionally group) as which ntpd will run.
.It Fl v Ar variable
.It Fl V Ar variable
Add a system variable listed by default.
.It Fl 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.
.El
.Sh THE CONFIGURATION FILE
The
.Nm
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
.Pa /etc
directory,
but could be installed elsewhere (see the
.Fl c
.Ar conffile
command line option). The file format is similar to other Unix
configuration files - comments begin with a
.Pa #
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 optional, 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
.Pa \&[ \&]
in the following
descriptions, while alternatives are separated by
.Pa \&| .
The
notation
.Pa [ ... ]
means an optional, indefinite repetition of
the last item before the
.Pa [ ... ]
.
.Pp
See the following pages for configuration and control options. While
there is a rich set of options available, the only required option is
one or more
.Pa server, peer,
.Pa broadcast
or
.Pa manycastclient
commands described in the Configuration Options
page. The
.%T "Notes on Configuring NTP and Setting up a NTP Subnet"
page in
.Pa /usr/share/doc/html/ntp/notes.htm
contains an extended discussion of these options.
For
.%T "Configuration Options" ,
refer to
.Pa /usr/share/doc/html/ntp/confopt.htm .
.Pp
For
.%T "Authentication Options" ,
refer to
.Pa /usr/share/doc/html/ntp/authopt.htm .
.Pp
For
.%T "Monitoring Options" ,
refer to
.Pa /usr/share/doc/html/ntp/monopt.htm .
.Pp
For
.%T "Access Control Options" ,
refer to
.Pa /usr/share/doc/html/ntp/accopt.htm .
.Pp
For
.%T "Reference Clock Options" ,
refer to
.Pa /usr/share/doc/html/ntp/clockopt.htm .
.Pp
For
.%T "Miscellaneous Options" ,
refer to
.Pa /usr/share/doc/html/ntp/miscopt.htm .
.Sh FILES
.Bl -tag -width /etc/ntp.drift -compact
.It Pa /etc/ntp.conf
the default name of the configuration file
.It Pa /etc/ntp.drift
the default name of the drift file
.It Pa /etc/ntp.keys
the default name of the key file
.El
.Sh AUTHORS
David L. Mills \*[Lt]mills@udel.edu\*[Gt]
.Sh BUGS
.Nm
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.