232 lines
5.6 KiB
Groff
232 lines
5.6 KiB
Groff
|
.\"
|
||
|
.\" $FreeBSD$
|
||
|
.\"
|
||
|
.Dd January 6, 2000
|
||
|
.Dt NTPDATE 8
|
||
|
.Os
|
||
|
.Sh NAME
|
||
|
.Nm ntpdate
|
||
|
.Nd set the date and time via NTP
|
||
|
.Sh SYNOPSIS
|
||
|
.Nm
|
||
|
.Op Fl bBdqsuv
|
||
|
.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 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 cron 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
|
||
|
.Nm
|
||
|
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
|
||
|
If NetInfo support is compiled into
|
||
|
.Nm Ns ,
|
||
|
then the server argument is optional if
|
||
|
.Nm
|
||
|
can find a time server in the NetInfo configuration for
|
||
|
.Xr ntpd 8 .
|
||
|
.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 .
|
||
|
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 - 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 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
|
||
|
.Sh FILES
|
||
|
.Bl -tag -width /etc/ntp.keys -compact
|
||
|
.It Pa /etc/ntp.keys
|
||
|
contains the encryption keys used by
|
||
|
.Nm Ns .
|
||
|
.El
|
||
|
.Sh SEE ALSO
|
||
|
.Xr ntpd 8
|
||
|
.Sh HISTORY
|
||
|
Written by
|
||
|
.An Dennis Ferguson
|
||
|
at the University of Toronto
|
||
|
.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 tick
|
||
|
and
|
||
|
.Va tickadj .
|