path: root/usr.sbin/ntp/doc/ntpd.8

.\"
.\" $FreeBSD$
.\"
.Dd January 10, 2000
.Dt NTPD 8
.Os
.Sh NAME
.Nm ntpd
.Nd Network Time Protocol (NTP) daemon
.Sh SYNOPSIS
.Nm ntpd
.Op Fl aAbdgmx
.Op Fl c Ar conffile
.Op Fl f Ar driftfile
.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 trustedkey
.Op Fl v Ar variable
.Op Fl V Ar variable
.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
.Xr ntp.conf 5
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 Ns ,
then
.Nm
will attempt to read its configuration from the NetInfo
if the default configuration 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
through use of the
.Xr ntpq 8
and
.Xr ntpdc 8
programs.
.Pp
When
.Nm
starts it looks at the value of
.Xr umask 2
and if it is zero,
.Nm
will set it to 022.
.Pp
The following command line options are available:
.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 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
between 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 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
.Ss Variables
Most variables used by the NTP protocol
can be examined with
.Xr ntpdc 8
(mode 7 messages) and
.Xr ntpq 8 (mode 6 messages).
Currently, very few variables can be modified via mode 6 messages.
These variables are either created with the
.Ic setvar
directive
(described in the
.Qq Miscellaneous Options
section of the
.Xr ntp.conf 5
page)
or the leap warning bits.
The leap warning bits can be set in the
.Va leapwarning
variable up to one month ahead.
Both the
.Va leapwarning
and
.Va leapindication
variables have a slightly different encoding
than the usual leap bits interpretation:
.Pp
.Bl -tag -width indent -compact
.It 00
The daemon passes the leap bits of its synchronization source
(usual mode of operation).
.It 01
.It 10
A leap second is added/deleted (operator forced leap second).
.It 11
Leap information from the synchronizations source is ignored
(thus
.Dv LEAP_NOWARNING
is passed on).
.El
.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 SEE ALSO
.Xr ntp.conf 5 ,
.Xr ntpdate 8 ,
.Xr ntpdc 8 ,
.Xr ntpq 8
.Pp
In addition to the manual pages provided,
comprehensive documentation is available on the world wide web
at
.Li http://www.ntp.org/ .
A snapshot of this documentation is available in HTML format in
.Pa /usr/share/doc/ntp .
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 1)
.%O RFC1059
.Re
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 2)
.%O RFC1119
.Re
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 3)
.%O RFC1305
.Re
.Sh HISTORY
Written by
.An Dennis Ferguson
at the University of Toronto.
Text amended by
.An David Mills
at the University of Delaware.
.Sh BUGS
.Nm
has gotten rather fat.
While not huge, it has gotten larger than might
be desireable 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.