199 lines
5.6 KiB
Groff
199 lines
5.6 KiB
Groff
.\" $NetBSD: ntpdate.8,v 1.7 1998/12/30 20:22:44 mcr Exp $
|
|
.\" Converted from HTML to mandoc by Christos Zoulas <christos@netbsd.org>
|
|
.\"
|
|
.Dd April 17, 1997
|
|
.Dt NTPDATE 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ntpdate
|
|
.Nd set the date and time via NTP
|
|
.Sh SYNOPSIS
|
|
.Nm ntpdate
|
|
.Op Fl bBdoqsuv
|
|
.Op Fl a Ar key
|
|
.Op Fl e Ar authdelay
|
|
.Op Fl k Ar keyfile
|
|
.Op Fl o Ar version
|
|
.Op Fl p Ar samples
|
|
.Op Fl t Ar timeout
|
|
.Ar server
|
|
.Op Ar ...
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
sets the local date and time by polling the
|
|
Network Time Protocol (NTP) server(s) given as the
|
|
.Ar server
|
|
arguments to determine the correct time. It must be run as root on the
|
|
local host. A number of samples are obtained from each of the servers
|
|
specified and a subset of the NTP clock filter and selection algorithms
|
|
are applied to select the best of these. Note that the accuracy and
|
|
reliability of
|
|
.Nm
|
|
depends on the number of servers, the number of polls each time it
|
|
is run and the interval between runs.
|
|
.Pp
|
|
.Nm
|
|
can be run manually as necessary to set the host clock, or it can
|
|
be run from the host startup script to set the clock at boot time.
|
|
This is useful in some cases to set the clock initially before
|
|
starting the NTP daemon
|
|
.Xr xntpd 8 .
|
|
It is also possible
|
|
to run
|
|
.Nm
|
|
from a
|
|
.Xr cron 8
|
|
script. However, it is important to note that
|
|
.Nm
|
|
with contrived
|
|
.Xr cron 8
|
|
scripts is no substitute for the NTP daemon, which
|
|
uses sophisticated algorithms to maximize accuracy and reliability while
|
|
minimizing resource use. Finally, since
|
|
.Nm
|
|
does not discipline the host clock frequency as does
|
|
.Xr xntpd 8 ,
|
|
the accuracy using
|
|
.Nm
|
|
is limited.
|
|
.Pp
|
|
Time adjustments are made by
|
|
.Nm
|
|
in one of two ways.
|
|
If
|
|
.Nm
|
|
determines the clock is in error more than 0.5
|
|
second it will simply step the time by calling the system
|
|
.Xr settimeofday 2
|
|
routine. If the error is less than 0.5
|
|
seconds, it will slew the time by calling the system
|
|
.Xr adjtime 2
|
|
routine. The latter technique is less disruptive
|
|
and more accurate when the error is small, and works quite well when
|
|
.Nm
|
|
is run by
|
|
.Xr cron 8
|
|
every hour or two.
|
|
.Pp
|
|
.Nm
|
|
will decline to set the date if an NTP server
|
|
daemon (e.g.,
|
|
.Xr xntpd 8 )
|
|
is running on the same host. When running
|
|
.Nm
|
|
on a regular basis from
|
|
.Xr cron 8
|
|
as an alternative to running a daemon, doing so once every hour or two
|
|
will result in precise enough timekeeping to avoid stepping the clock.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl a Ar key
|
|
Enable the authentication function and specify the key identifier to
|
|
be used for authentication as the argument
|
|
.Ar key
|
|
.Nm
|
|
The keys and key identifiers must match
|
|
in both the client and server key files. The default is to disable the
|
|
authentication function.
|
|
.It Fl B
|
|
Force the time to always be slewed using the
|
|
.Xr adjtime 2
|
|
system call,
|
|
even if the measured offset is greater than +-128 ms. The default is to
|
|
step the time using
|
|
.Xr settimeofday 2
|
|
if the offset is greater than +-128
|
|
ms. Note that, if the offset is much greater than +-128 ms in this case,
|
|
that it can take a long time (hours) to slew the clock to the correct
|
|
value. During this time. the host should not be used to synchronize
|
|
clients.
|
|
.It Fl b
|
|
Force the time to be stepped using the
|
|
.Xr settimeofday 2
|
|
system call,
|
|
rather than slewed (default) using the
|
|
.Xr adjtime 2
|
|
system call. This
|
|
option should be used when called from a startup file at boot time.
|
|
.It Fl d
|
|
Enable the debugging mode, in which
|
|
.Nm
|
|
will go
|
|
through all the steps, but not adjust the local clock. Information
|
|
useful for general debugging will also be printed.
|
|
.It Fl e Ar authdelay
|
|
Specify the processing delay to perform an authentication function
|
|
as the value
|
|
.Ar authdelay ,
|
|
in seconds and fraction (see
|
|
.Xr xntpd 8
|
|
for details). This number is usually small enough to
|
|
be negligible for most purposes, though specifying a value may improve
|
|
timekeeping on very slow CPU's.
|
|
.It Fl k Ar keyfile
|
|
Specify the path for the authentication key file as the string
|
|
.Ar keyfile .
|
|
The default is
|
|
.Pa /etc/ntp.keys .
|
|
This file should be in the format described in
|
|
.Xr xntpd 8 .
|
|
.It Fl o Ar version
|
|
Specify the NTP version for outgoint packets as the integer
|
|
.Ar version ,
|
|
which can be 1 or 2. The default is 3. This allows
|
|
.Nm
|
|
to be used with older NTP versions.
|
|
.It Fl p Ar samples
|
|
Specify the number of samples to be acquired from each server as the
|
|
integer
|
|
.Ar samples ,
|
|
with values from 1 to 8 inclusive. The default is 4.
|
|
.It Fl q
|
|
Query only - don't set the clock.
|
|
.It Fl s
|
|
Divert logging output from the standard output (default) to the
|
|
system
|
|
.Xr syslog 3
|
|
facility. This is designed primarily for convenience of
|
|
.Xr cron 8
|
|
scripts.
|
|
.It Fl t Ar timeout
|
|
Specify the maximum time waiting for a server response as the value
|
|
.Ar timeout ,
|
|
in seconds and fraction. The value is is rounded to a
|
|
multiple of 0.2 seconds. The default is 1 second, a value suitable for
|
|
polling across a LAN.
|
|
.It Fl u
|
|
Direct
|
|
.Nm
|
|
to use an unprivileged port or outgoing
|
|
packets. This is most useful when behind a firewall that blocks incoming
|
|
traffic to privileged ports, and you want to synchronise with hosts
|
|
beyond the firewall. Note that the
|
|
.Fl d
|
|
option always uses
|
|
unprivileged ports.
|
|
.It Fl v
|
|
Be verbose. This option will cause the
|
|
.Nm
|
|
version
|
|
identification string to be logged.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/ntp.keys -compact
|
|
.It Pa /etc/gettytab
|
|
.It Pa /usr/share/doc/xntp/index.html
|
|
.It Pa /usr/share/doc/xntp/ntpdate.html
|
|
.El
|
|
.Sh BUGS
|
|
The slew adjustment is actually 50% larger than the measured offset,
|
|
since this (it is argued) will tend to keep a badly drifting clock more
|
|
accurate. This is probably not a good idea and may cause a troubling
|
|
hunt for some values of the kernel variables
|
|
.Xr tick 9
|
|
and
|
|
.Xr tickadj 9 .
|
|
.Sh AUTHOR
|
|
David L. Mills (mills@udel.edu)
|