1 files changed, 231 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..2049d15
--- /dev/null
+++ b/usr.sbin/ntp/doc/ntpdate.8
@@ -0,0 +1,231 @@
+.\"
+.\" $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 .