1 files changed, 279 insertions, 0 deletions
diff --git a/usr.sbin/ntp/doc/ntpdate.8 b/usr.sbin/ntp/doc/ntpdate.8
new file mode 100644
index 0000000..e5aaecd
--- /dev/null
+++ b/usr.sbin/ntp/doc/ntpdate.8
@@ -0,0 +1,279 @@
+.\"
+.\" $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 .