280 lines
6.2 KiB
Groff
280 lines
6.2 KiB
Groff
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 17, 2006
|
|
.Dt NTPDATE 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ntpdate
|
|
.Nd set the date and time via NTP
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl 46bBdoqsuv
|
|
.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 ...
|
|
.Sh DESCRIPTION
|
|
.Em Note :
|
|
The functionality of this program is now available
|
|
in the
|
|
.Xr ntpd 8
|
|
program.
|
|
See the
|
|
.Fl q
|
|
command line
|
|
option in the
|
|
.Xr ntpd 8
|
|
page.
|
|
After a suitable period of
|
|
mourning, the
|
|
.Nm
|
|
utility is to be retired from this
|
|
distribution.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility 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
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl 4
|
|
Force DNS resolution of following host names on the command line to the
|
|
IPv4 namespace.
|
|
.It Fl 6
|
|
Force DNS resolution of following host names on the command line to the
|
|
IPv6 namespace.
|
|
.It Fl a Ar key
|
|
Enable the authentication function and specify the key
|
|
identifier to be used for authentication as the argument
|
|
.Ar key .
|
|
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, 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 ntpd 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 ntpd 8 .
|
|
.It Fl o Ar version
|
|
Specify the NTP version for outgoing 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 - do not 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
|
|
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 for 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
|
|
.Nm Ns 's
|
|
version
|
|
identification string to be logged.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility 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 ntpd 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 ntpd 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
|
|
The
|
|
.Nm
|
|
utility will decline to set the date if an NTP server
|
|
daemon (e.g.,
|
|
.Xr ntpd 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
|
|
Note that in contexts where a host name is expected, a
|
|
.Fl 4
|
|
qualifier preceding the host name forces DNS resolution to the
|
|
IPv4 namespace, while a
|
|
.Fl 6
|
|
qualifier forces DNS resolution to the IPv6 namespace.
|
|
.Pp
|
|
If NetInfo support is compiled into
|
|
.Nm ,
|
|
then the
|
|
.Cm server
|
|
argument is optional if
|
|
.Nm
|
|
can find a
|
|
time server in the NetInfo configuration for
|
|
.Xr ntpd 8 .
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/ntp.keys -compact
|
|
.It Pa /etc/ntp.keys
|
|
contains the encryption keys used by
|
|
.Nm .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ntpd 8
|
|
.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
|
|
.Va kern.clockrate.tick
|
|
and
|
|
.Va kern.clockrate.tickadj .
|