This commit was manufactured by cvs2svn to create tag 'FreeBSD-release/1.1'.

[unix-history] / contrib / xntpd / doc / ntpdate.8

''' $Header
''' 
.de Sh
.br
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Greek uppercase omega is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.ie n \{\
.ds -- \(*W-
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
.ds L' '
.ds R' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds L' `
.ds R' '
'br\}
.TH NTPDATE 8 LOCAL
.SH NAME
ntpdate - set the date and time via NTP
.SH SYNOPSIS
.B ntpdate
[
.B -bdos
] [
.B -a
.I key#
] [
.B -e
.I authdelay
] [
.B -k
.I keyfile
] [
.B -p
.I samples
] [
.B -t
.I timeout
]
server ...
.SH DESCRIPTION
.I Ntpdate
sets the local date and time by polling the Network Time Protocol
server(s) on the host(s) given as 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 the
standard NTP clock filter and selection algorithms are applied to select
the best of these.  Typically,
.I ntpdate
can be inserted in the
.I /etc/rc.local
startup up script to set the time of day at boot time and/or can be run
from time\-to\-time via
.IR cron (8).
Note that
.IR ntpdate 's
reliability and precision will improve dramatically with greater numbers
of servers.  While a single server may be used, better performance and
greater resistance to insanity on the part of any one server
will be obtained by providing at least three or four servers, if not more.
.PP
Time adjustments are made by
.I ntpdate
in one of two ways.  If
.I ntpdate
determines your clock is off by more than 0.5 seconds it will simply
step the time by calling
.IR settimeofday (2).
If the error is less than 0.5 seconds, however, it will by default slew
the clock's time via a call to
.IR adjtime (2)
with the offset.  The latter technique is less disruptive and more
accurate when the offset is small, and works quite well when
.I ntpdate
is run by
.I cron (8)
every hour or two.  The adjustment made in the latter
case is actually 50% larger than the measured offset since this will
tend to keep a badly drifting clock more accurate (at some expense to
stability, though this tradeoff is usually advantageous).  At boot time,
however, it is usually better to always step the time.  This can be forced
in all cases by specifying the
.B -b
switch on the command line.  The
.B -s
switch tells
.I ntpdate
to log its actions via the
.IR syslog (3)
facility rather than to the standard output, a useful option when
running the program from
.IR cron (8).
.PP
The
.B -d
flag may be used to determine what
.I ntpdate
will do without it actually doing it.  Information useful for general
debugging will also be printed.  By default
.I ntpdate
claims to be an NTP version 2 implementation in its outgoing packets.  As
some older software will decline to respond to version 2 queries, the
.B -o
switch can be used to force the program to poll as a version 1 implementation
instead.
.PP
The number of samples
.I ntpdate
acquires from each server can be set to between 1 and 8 inclusive
using the
.B -p
switch.  The default is 4.  The time it will spend waiting for a
response can be set using the
.B -t
switch, and will be rounded to a multiple of 0.2 seconds.  The default
is 1 second, a value suitable for polling across a LAN.
.PP
.I Ntpdate
will authenticate its transactions if need be.  The
.B -a
switch specifies that all packets should be authenticated using the
key number indicated.  The
.B -k
switch allows the name of the file from which the keys may be read
to be modified from the default of
.I /etc/ntp.keys.
This file should be in the format described in
.IR xntpd (8).
The
.B -e
option allows the specification of an authentication processing delay,
in seconds (see
.IR xntpd (8)
for details).  This number is usually small enough to be negligible for
.IR ntpdate 's
purposes, though specifying a value may improve timekeeping on very slow
CPU's.
.PP
.I Ntpdate
will decline to set the date if an NTP server daemon (e.g.
.IR xntpd (8))
is running on the same host.  When running
.I ntpdate
on a regular basis from
.IR 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.
.SH FILES
.nf
/etc/ntp.keys\0\0contains the encription keys used by \fIntpdate\fP.
.fi
.SH SEE ALSO
xntpd(8)
.SH HISTORY
Written by Dennis Ferguson at the University of Toronto
.SH BUGS
The technique used for improving accuracy by compensating for clock
oscillator errors sucks, but doing better would require the program
to save state from previous runs.