jimzah/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src.git synced 2024-11-26 20:12:44 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

ntp: Switch to upstream man pages

Browse Source 
The downstream (FreeBSD) ntp man pages are out of date. Switch to those
provided by ntp.org (nwtime.org).

PR:			104493
Differential Revision:	https://reviews.freebsd.org/D47319
This commit is contained in:
Cy Schubert 2024-10-28 09:33:30 -07:00
parent 195402c5c5
commit c607b3258f
8 changed files with 38 additions and 7764 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
usr.sbin/ntp/doc/Makefile
View File

@ -24,9 +24,46 @@ FILES= access.html accopt.html assoc.html audio.html authentic.html \
MAN= ntp.conf.5 ntp.keys.5
MAN+= ntp-keygen.8 ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 sntp.8
CLEANFILES= ntp.conf.5 ntp.keys.5
CLEANFILES+= ntp-keygen.8 ntpd.8 ntpdc.8 ntpq.8 sntp.8
SUFFIXES8= .1ntp-keygenmdoc \
.1ntpdmdoc \
.1ntpdcmdoc \
.1ntpqmdoc \
.1sntpmdoc
.SUFFIXES: .html .5 .8 .5mdoc ${SUFFIXES8}
.5mdoc.5:
sed '/^\.Dt /s/5mdoc/5/' ${.ALLSRC} > ${.TARGET}
.for s in ${SUFFIXES8}
$s.8:
sed '/^\.Dt /s/1[a-z-][a-z-]*/8/' ${.ALLSRC} > ${.TARGET}
.endfor
ntp.conf.5: ntp.conf.5mdoc
ntp.keys.5: ntp.keys.5mdoc
ntp-keygen.8: ntp-keygen.1ntp-keygenmdoc
ntpd.8: ntpd.1ntpdmdoc
ntpdc.8: ntpdc.1ntpdcmdoc
ntpq.8: ntpq.1ntpqmdoc
sntp.8: sntp.1sntpmdoc
.PATH: ${SRCTOP}/contrib/ntp/html \
${SRCTOP}/contrib/ntp/util \
${SRCTOP}/contrib/ntp/ntpd \
${SRCTOP}/contrib/ntp/ntpsnmpd
${SRCTOP}/contrib/ntp/ntpdc \
${SRCTOP}/contrib/ntp/ntpq \
${SRCTOP}/contrib/ntp/ntpsnmpd \
${SRCTOP}/contrib/ntp/sntp \
${SRCTOP}/contrib/ntp/util
.include <bsd.prog.mk>

1223
usr.sbin/ntp/doc/ntp-keygen.8
View File

File diff suppressed because it is too large Load Diff

3277
usr.sbin/ntp/doc/ntp.conf.5
View File

File diff suppressed because it is too large Load Diff

174
usr.sbin/ntp/doc/ntp.keys.5
View File

@ -1,174 +0,0 @@
.Dd August 14 2018
.Dt NTP_KEYS 5 File Formats
.Os SunOS 5.10
.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc)
.\"
.\" It has been AutoGen-ed August 14, 2018 at 08:29:18 AM by AutoGen 5.18.5
.\" From the definitions ntp.keys.def
.\" and the template file agmdoc-file.tpl
.Sh NAME
.Nm ntp.keys
.Nd NTP symmetric key file format
.Sh NAME
.Nm ntp.keys
.Nd Network Time Protocol symmetric key format
.Sh SYNOPSIS
.Nm
.Op Fl \-option\-name
.Op Fl \-option\-name Ar value
.Pp
All arguments must be options.
.Pp
.Sh DESCRIPTION
This document describes the format of an NTP symmetric key file.
For a description of the use of this type of file, see the
.Qq Authentication Support
section of the
.Xr ntp.conf 5
page.
.Pp
.Xr ntpd 8
reads its keys from a file specified using the
.Fl k
command line option or the
.Ic keys
statement in the configuration file.
While key number 0 is fixed by the NTP standard
(as 56 zero bits)
and may not be changed,
one or more keys numbered between 1 and 65535
may be arbitrarily set in the keys file.
.Pp
The key file uses the same comment conventions
as the configuration file.
Key entries use a fixed format of the form
.Pp
.D1 Ar keyno type key opt_IP_list
.Pp
where
.Ar keyno
is a positive integer (between 1 and 65535),
.Ar type
is the message digest algorithm,
.Ar key
is the key itself, and
.Ar opt_IP_list
is an optional comma\-separated list of IPs
where the
.Ar keyno
should be trusted.
that are allowed to serve time.
Each IP in
.Ar opt_IP_list
may contain an optional
.Cm /subnetbits
specification which identifies the number of bits for
the desired subnet of trust.
If
.Ar opt_IP_list
is empty,
any properly\-authenticated message will be
accepted.
.Pp
The
.Ar key
may be given in a format
controlled by the
.Ar type
field.
The
.Ar type
.Li MD5
is always supported.
If
.Li ntpd
was built with the OpenSSL library
then any digest library supported by that library may be specified.
However, if compliance with FIPS 140\-2 is required the
.Ar type
must be either
.Li SHA
or
.Li SHA1 .
.Pp
What follows are some key types, and corresponding formats:
.Pp
.Bl -tag -width RMD160 -compact
.It Li MD5
The key is 1 to 16 printable characters terminated by
an EOL,
whitespace,
or
a
.Li #
(which is the "start of comment" character).
.Pp
.It Li SHA
.It Li SHA1
.It Li RMD160
The key is a hex\-encoded ASCII string of 40 characters,
which is truncated as necessary.
.El
.Pp
Note that the keys used by the
.Xr ntpq 8
and
.Xr ntpdc 8
programs are checked against passwords
requested by the programs and entered by hand,
so it is generally appropriate to specify these keys in ASCII format.
.Sh "OPTIONS"
.Bl -tag
.It Fl \-help
Display usage information and exit.
.It Fl \-more\-help
Pass the extended usage information through a pager.
.It Fl \-version Op Brq Ar v|c|n
Output version of program and exit. The default mode is `v', a simple
version. The `c' mode will print copyright information and `n' will
print the full copyright notice.
.El
.Sh "OPTION PRESETS"
Any option that is not marked as \fInot presettable\fP may be preset
by loading values from environment variables named:
.nf
\fBNTP_KEYS_<option\-name>\fP or \fBNTP_KEYS\fP
.fi
.ad
.Sh "ENVIRONMENT"
See \fBOPTION PRESETS\fP for configuration environment variables.
.Sh FILES
.Bl -tag -width /etc/ntp.keys -compact
.It Pa /etc/ntp.keys
the default name of the configuration file
.El
.Sh "EXIT STATUS"
One of the following exit values will be returned:
.Bl -tag
.It 0 " (EXIT_SUCCESS)"
Successful program execution.
.It 1 " (EXIT_FAILURE)"
The operation failed or the command syntax was not valid.
.It 70 " (EX_SOFTWARE)"
libopts had an internal operational error. Please report
it to autogen\-users@lists.sourceforge.net. Thank you.
.El
.Sh "SEE ALSO"
.Xr ntp.conf 5 ,
.Xr ntpd 8 ,
.Xr ntpdate 8 ,
.Xr ntpdc 8 ,
.Xr sntp 8
.Sh "AUTHORS"
The University of Delaware and Network Time Foundation
.Sh "COPYRIGHT"
Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved.
This program is released under the terms of the NTP license, <http://ntp.org/license>.
.Sh "BUGS"
Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
.Sh NOTES
This document was derived from FreeBSD.
.Pp
This manual page was \fIAutoGen\fP\-erated from the \fBntp.keys\fP
option definitions.

908
usr.sbin/ntp/doc/ntpd.8
View File

@ -1,908 +0,0 @@
.Dd August 14 2018
.Dt NTPD 8 User Commands
.Os
.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc)
.\"
.\" It has been AutoGen-ed August 14, 2018 at 08:29:20 AM by AutoGen 5.18.5
.\" From the definitions ntpd-opts.def
.\" and the template file agmdoc-cmd.tpl
.Sh NAME
.Nm ntpd
.Nd set clock via Network Time Protocol daemon
.Sh SYNOPSIS
.Nm
.\" Mixture of short (flag) options and long options
.Op Fl flags
.Op Fl flag Op Ar value
.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
[ <server1> ... <serverN> ]
.Pp
.Sh DESCRIPTION
The
.Nm
utility is an operating system daemon which sets
and maintains the system time of day in synchronism with Internet
standard time servers.
It is a complete implementation of the
Network Time Protocol (NTP) version 4, as defined by RFC\-5905,
but also retains compatibility with
version 3, as defined by RFC\-1305, and versions 1
and 2, as defined by RFC\-1059 and RFC\-1119, respectively.
.Pp
The
.Nm
utility does most computations in 64\-bit floating point
arithmetic and does relatively clumsy 64\-bit fixed point operations
only when necessary to preserve the ultimate precision, about 232
picoseconds.
While the ultimate precision is not achievable with
ordinary workstations and networks of today, it may be required
with future gigahertz CPU clocks and gigabit LANs.
.Pp
Ordinarily,
.Nm
reads the
.Xr ntp.conf 5
configuration file at startup time in order to determine the
synchronization sources and operating modes.
It is also possible to
specify a working, although limited, configuration entirely on the
command line, obviating the need for a configuration file.
This may
be particularly useful when the local host is to be configured as a
broadcast/multicast client, with all peers being determined by
listening to broadcasts at run time.
.Pp
If NetInfo support is built into
.Nm ,
then
.Nm
will attempt to read its configuration from the
NetInfo if the default
.Xr ntp.conf 5
file cannot be read and no file is
specified by the
.Fl c
option.
.Pp
Various internal
.Nm
variables can be displayed and
configuration options altered while the
.Nm
is running
using the
.Xr ntpq 8
and
.Xr ntpdc 8
utility programs.
.Pp
When
.Nm
starts it looks at the value of
.Xr umask 2 ,
and if zero
.Nm
will set the
.Xr umask 2
to 022.
.Sh "OPTIONS"
.Bl -tag
.It Fl 4 , Fl \-ipv4
Force IPv4 DNS name resolution.
This option must not appear in combination with any of the following options:
ipv6.
.sp
Force DNS resolution of following host names on the command line
to the IPv4 namespace.
.It Fl 6 , Fl \-ipv6
Force IPv6 DNS name resolution.
This option must not appear in combination with any of the following options:
ipv4.
.sp
Force DNS resolution of following host names on the command line
to the IPv6 namespace.
.It Fl a , Fl \-authreq
Require crypto authentication.
This option must not appear in combination with any of the following options:
authnoreq.
.sp
Require cryptographic authentication for broadcast client,
multicast client and symmetric passive associations.
This is the default.
.It Fl A , Fl \-authnoreq
Do not require crypto authentication.
This option must not appear in combination with any of the following options:
authreq.
.sp
Do not require cryptographic authentication for broadcast client,
multicast client and symmetric passive associations.
This is almost never a good idea.
.It Fl b , Fl \-bcastsync
Allow us to sync to broadcast servers.
.sp
.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string
configuration file name.
.sp
The name and path of the configuration file,
\fI/etc/ntp.conf\fP
by default.
.It Fl d , Fl \-debug\-level
Increase debug verbosity level.
This option may appear an unlimited number of times.
.sp
.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
Set the debug verbosity level.
This option may appear an unlimited number of times.
This option takes an integer number as its argument.
.sp
.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string
frequency drift file name.
.sp
The name and path of the frequency file,
\fI/etc/ntp.drift\fP
by default.
This is the same operation as the
\fBdriftfile\fP \fIdriftfile\fP
configuration specification in the
\fI/etc/ntp.conf\fP
file.
.It Fl g , Fl \-panicgate
Allow the first adjustment to be Big.
This option may appear an unlimited number of times.
.sp
Normally,
\fBntpd\fP
exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that,
\fBntpd\fP
will exit with a message to the system log. This option can be used with the
\fB\-q\fP
and
\fB\-x\fP
options.
See the
\fBtinker\fP
configuration file directive for other options.
.It Fl G , Fl \-force\-step\-once
Step any initial offset correction..
.sp
Normally,
\fBntpd\fP
steps the time if the time offset exceeds the step threshold,
which is 128 ms by default, and otherwise slews the time.
This option forces the initial offset correction to be stepped,
so the highest time accuracy can be achieved quickly.
However, this may also cause the time to be stepped back
so this option must not be used if
applications requiring monotonic time are running.
See the \fBtinker\fP configuration file directive for other options.
.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string
Jail directory.
.sp
Chroot the server to the directory
\fIjaildir\fP
.
This option also implies that the server attempts to drop root privileges at startup.
You may need to also specify a
\fB\-u\fP
option.
This option is only available if the OS supports adjusting the clock
without full root privileges.
This option is supported under NetBSD (configure with
\fB\-\-enable\-clockctl\fP) or Linux (configure with
\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP).
.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface
Listen on an interface name or address.
This option may appear an unlimited number of times.
.sp
Open the network address given, or all the addresses associated with the
given interface name. This option may appear multiple times. This option
also implies not opening other addresses, except wildcard and localhost.
This option is deprecated. Please consider using the configuration file
\fBinterface\fP command, which is more versatile.
.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string
path to symmetric keys.
.sp
Specify the name and path of the symmetric key file.
\fI/etc/ntp.keys\fP
is the default.
This is the same operation as the
\fBkeys\fP \fIkeyfile\fP
configuration file directive.
.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string
path to the log file.
.sp
Specify the name and path of the log file.
The default is the system log file.
This is the same operation as the
\fBlogfile\fP \fIlogfile\fP
configuration file directive.
.It Fl L , Fl \-novirtualips
Do not listen to virtual interfaces.
.sp
Do not listen to virtual interfaces, defined as those with
names containing a colon. This option is deprecated. Please
consider using the configuration file \fBinterface\fP command, which
is more versatile.
.It Fl M , Fl \-modifymmtimer
Modify Multimedia Timer (Windows only).
.sp
Set the Windows Multimedia Timer to highest resolution. This
ensures the resolution does not change while ntpd is running,
avoiding timekeeping glitches associated with changes.
.It Fl n , Fl \-nofork
Do not fork.
This option must not appear in combination with any of the following options:
wait\-sync.
.sp
.It Fl N , Fl \-nice
Run at high priority.
.sp
To the extent permitted by the operating system, run
\fBntpd\fP
at the highest priority.
.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string
path to the PID file.
.sp
Specify the name and path of the file used to record
\fBntpd\fP's
process ID.
This is the same operation as the
\fBpidfile\fP \fIpidfile\fP
configuration file directive.
.It Fl P Ar number , Fl \-priority Ns = Ns Ar number
Process priority.
This option takes an integer number as its argument.
.sp
To the extent permitted by the operating system, run
\fBntpd\fP
at the specified
\fBsched_setscheduler(SCHED_FIFO)\fP
priority.
.It Fl q , Fl \-quit
Set the time and quit.
This option must not appear in combination with any of the following options:
saveconfigquit, wait\-sync.
.sp
\fBntpd\fP
will not daemonize and will exit after the clock is first
synchronized. This behavior mimics that of the
\fBntpdate\fP
program, which will soon be replaced with a shell script.
The
\fB\-g\fP
and
\fB\-x\fP
options can be used with this option.
Note: The kernel time discipline is disabled with this option.
.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string
Broadcast/propagation delay.
.sp
Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol.
.It Fl \-saveconfigquit Ns = Ns Ar string
Save parsed configuration and quit.
This option must not appear in combination with any of the following options:
quit, wait\-sync.
.sp
Cause \fBntpd\fP to parse its startup configuration file and save an
equivalent to the given filename and exit. This option was
designed for automated testing.
.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string
Statistics file location.
.sp
Specify the directory path for files created by the statistics facility.
This is the same operation as the
\fBstatsdir\fP \fIstatsdir\fP
configuration file directive.
.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey
Trusted key number.
This option may appear an unlimited number of times.
.sp
Add the specified key number to the trusted key list.
.It Fl u Ar string , Fl \-user Ns = Ns Ar string
Run as userid (or userid:groupid).
.sp
Specify a user, and optionally a group, to switch to.
This option is only available if the OS supports adjusting the clock
without full root privileges.
This option is supported under NetBSD (configure with
\fB\-\-enable\-clockctl\fP) or Linux (configure with
\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP).
.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number
interval in seconds between scans for new or dropped interfaces.
This option takes an integer number as its argument.
.sp
Give the time in seconds between two scans for new or dropped interfaces.
For systems with routing socket support the scans will be performed shortly after the interface change
has been detected by the system.
Use 0 to disable scanning. 60 seconds is the minimum time between scans.
.It Fl \-var Ns = Ns Ar nvar
make ARG an ntp variable (RW).
This option may appear an unlimited number of times.
.sp
.It Fl \-dvar Ns = Ns Ar ndvar
make ARG an ntp variable (RW|DEF).
This option may appear an unlimited number of times.
.sp
.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number
Seconds to wait for first clock sync.
This option must not appear in combination with any of the following options:
nofork, quit, saveconfigquit.
This option takes an integer number as its argument.
.sp
If greater than zero, alters \fBntpd\fP's behavior when forking to
daemonize. Instead of exiting with status 0 immediately after
the fork, the parent waits up to the specified number of
seconds for the child to first synchronize the clock. The exit
status is zero (success) if the clock was synchronized,
otherwise it is \fBETIMEDOUT\fP.
This provides the option for a script starting \fBntpd\fP to easily
wait for the first set of the clock before proceeding.
.It Fl x , Fl \-slew
Slew up to 600 seconds.
.sp
Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold.
This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually.
Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s.
Thus, an adjustment as much as 600 s will take almost 14 days to complete.
This option can be used with the
\fB\-g\fP
and
\fB\-q\fP
options.
See the
\fBtinker\fP
configuration file directive for other options.
Note: The kernel time discipline is disabled with this option.
.It Fl \-usepcc
Use CPU cycle counter (Windows only).
.sp
Attempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP.
The CPU counter and \fBQueryPerformanceCounter\fP are compared, and if
they have the same frequency, the CPU counter (RDTSC on x86) is
used directly, saving the overhead of a system call.
.It Fl \-pccfreq Ns = Ns Ar string
Force CPU cycle counter use (Windows only).
.sp
Force substitution the CPU counter for \fBQueryPerformanceCounter\fP.
The CPU counter (RDTSC on x86) is used unconditionally with the
given frequency (in Hz).
.It Fl m , Fl \-mdns
Register with mDNS as a NTP server.
.sp
Registers as an NTP server with the local mDNS server which allows
the server to be discovered via mDNS client lookup.
.It Fl \&? , Fl \-help
Display usage information and exit.
.It Fl \&! , Fl \-more\-help
Pass the extended usage information through a pager.
.It Fl \-version Op Brq Ar v|c|n
Output version of program and exit. The default mode is `v', a simple
version. The `c' mode will print copyright information and `n' will
print the full copyright notice.
.El
.Sh "OPTION PRESETS"
Any option that is not marked as \fInot presettable\fP may be preset
by loading values from environment variables named:
.nf
\fBNTPD_<option\-name>\fP or \fBNTPD\fP
.fi
.ad
.Sh USAGE
.Ss "How NTP Operates"
The
.Nm
utility operates by exchanging messages with
one or more configured servers over a range of designated poll intervals.
When
started, whether for the first or subsequent times, the program
requires several exchanges from the majority of these servers so
the signal processing and mitigation algorithms can accumulate and
groom the data and set the clock.
In order to protect the network
from bursts, the initial poll interval for each server is delayed
an interval randomized over a few seconds.
At the default initial poll
interval of 64s, several minutes can elapse before the clock is
set.
This initial delay to set the clock
can be safely and dramatically reduced using the
.Cm iburst
keyword with the
.Ic server
configuration
command, as described in
.Xr ntp.conf 5 .
.Pp
Most operating systems and hardware of today incorporate a
time\-of\-year (TOY) chip to maintain the time during periods when
the power is off.
When the machine is booted, the chip is used to
initialize the operating system time.
After the machine has
synchronized to a NTP server, the operating system corrects the
chip from time to time.
In the default case, if
.Nm
detects that the time on the host
is more than 1000s from the server time,
.Nm
assumes something must be terribly wrong and the only
reliable action is for the operator to intervene and set the clock
by hand.
(Reasons for this include there is no TOY chip,
or its battery is dead, or that the TOY chip is just of poor quality.)
This causes
.Nm
to exit with a panic message to
the system log.
The
.Fl g
option overrides this check and the
clock will be set to the server time regardless of the chip time
(up to 68 years in the past or future \(em
this is a limitation of the NTPv4 protocol).
However, and to protect against broken hardware, such as when the
CMOS battery fails or the clock counter becomes defective, once the
clock has been set an error greater than 1000s will cause
.Nm
to exit anyway.
.Pp
Under ordinary conditions,
.Nm
adjusts the clock in
small steps so that the timescale is effectively continuous and
without discontinuities.
Under conditions of extreme network
congestion, the roundtrip delay jitter can exceed three seconds and
the synchronization distance, which is equal to one\-half the
roundtrip delay plus error budget terms, can become very large.
The
.Nm
algorithms discard sample offsets exceeding 128 ms,
unless the interval during which no sample offset is less than 128
ms exceeds 900s.
The first sample after that, no matter what the
offset, steps the clock to the indicated time.
In practice this
reduces the false alarm rate where the clock is stepped in error to
a vanishingly low incidence.
.Pp
As the result of this behavior, once the clock has been set it
very rarely strays more than 128 ms even under extreme cases of
network path congestion and jitter.
Sometimes, in particular when
.Nm
is first started without a valid drift file
on a system with a large intrinsic drift
the error might grow to exceed 128 ms,
which would cause the clock to be set backwards
if the local clock time is more than 128 s
in the future relative to the server.
In some applications, this behavior may be unacceptable.
There are several solutions, however.
If the
.Fl x
option is included on the command line, the clock will
never be stepped and only slew corrections will be used.
But this choice comes with a cost that
should be carefully explored before deciding to use
the
.Fl x
option.
The maximum slew rate possible is limited
to 500 parts\-per\-million (PPM) as a consequence of the correctness
principles on which the NTP protocol and algorithm design are
based.
As a result, the local clock can take a long time to
converge to an acceptable offset, about 2,000 s for each second the
clock is outside the acceptable range.
During this interval the
local clock will not be consistent with any other network clock and
the system cannot be used for distributed applications that require
correctly synchronized network time.
.Pp
In spite of the above precautions, sometimes when large
frequency errors are present the resulting time offsets stray
outside the 128\-ms range and an eventual step or slew time
correction is required.
If following such a correction the
frequency error is so large that the first sample is outside the
acceptable range,
.Nm
enters the same state as when the
.Pa ntp.drift
file is not present.
The intent of this behavior
is to quickly correct the frequency and restore operation to the
normal tracking mode.
In the most extreme cases
(the host
.Cm time.ien.it
comes to mind), there may be occasional
step/slew corrections and subsequent frequency corrections.
It
helps in these cases to use the
.Cm burst
keyword when
configuring the server, but
ONLY
when you have permission to do so from the owner of the target host.
.Pp
Finally,
in the past many startup scripts would run
.Xr ntpdate 8
or
.Xr sntp 8
to get the system clock close to correct before starting
.Xr ntpd 8 ,
but this was never more than a mediocre hack and is no longer needed.
If you are following the instructions in
.Sx "Starting NTP (Best Current Practice)"
and you still need to set the system time before starting
.Nm ,
please open a bug report and document what is going on,
and then look at using
.Xr sntp 8
if you really need to set the clock before starting
.Nm .
.Pp
There is a way to start
.Xr ntpd 8
that often addresses all of the problems mentioned above.
.Ss "Starting NTP (Best Current Practice)"
First, use the
.Cm iburst
option on your
.Cm server
entries.
.Pp
If you can also keep a good
.Pa ntp.drift
file then
.Xr ntpd 8
will effectively "warm\-start" and your system's clock will
be stable in under 11 seconds' time.
.Pp
As soon as possible in the startup sequence, start
.Xr ntpd 8
with at least the
.Fl g
and perhaps the
.Fl N
options.
Then,
start the rest of your "normal" processes.
This will give
.Xr ntpd 8
as much time as possible to get the system's clock synchronized and stable.
.Pp
Finally,
if you have processes like
.Cm dovecot
or database servers
that require
monotonically\-increasing time,
run
.Xr ntp\-wait 1ntp\-waitmdoc
as late as possible in the boot sequence
(perhaps with the
.Fl v
flag)
and after
.Xr ntp\-wait 1ntp\-waitmdoc
exits successfully
it is as safe as it will ever be to start any process that require
stable time.
.Ss "Frequency Discipline"
The
.Nm
behavior at startup depends on whether the
frequency file, usually
.Pa ntp.drift ,
exists.
This file
contains the latest estimate of clock frequency error.
When the
.Nm
is started and the file does not exist, the
.Nm
enters a special mode designed to quickly adapt to
the particular system clock oscillator time and frequency error.
This takes approximately 15 minutes, after which the time and
frequency are set to nominal values and the
.Nm
enters
normal mode, where the time and frequency are continuously tracked
relative to the server.
After one hour the frequency file is
created and the current frequency offset written to it.
When the
.Nm
is started and the file does exist, the
.Nm
frequency is initialized from the file and enters normal mode
immediately.
After that the current frequency offset is written to
the file at hourly intervals.
.Ss "Operating Modes"
The
.Nm
utility can operate in any of several modes, including
symmetric active/passive, client/server broadcast/multicast and
manycast, as described in the
.Qq Association Management
page
(available as part of the HTML documentation
provided in
.Pa /usr/share/doc/ntp ) .
It normally operates continuously while
monitoring for small changes in frequency and trimming the clock
for the ultimate precision.
However, it can operate in a one\-time
mode where the time is set from an external server and frequency is
set from a previously recorded frequency file.
A
broadcast/multicast or manycast client can discover remote servers,
compute server\-client propagation delay correction factors and
configure itself automatically.
This makes it possible to deploy a
fleet of workstations without specifying configuration details
specific to the local environment.
.Pp
By default,
.Nm
runs in continuous mode where each of
possibly several external servers is polled at intervals determined
by an intricate state machine.
The state machine measures the
incidental roundtrip delay jitter and oscillator frequency wander
and determines the best poll interval using a heuristic algorithm.
Ordinarily, and in most operating environments, the state machine
will start with 64s intervals and eventually increase in steps to
1024s.
A small amount of random variation is introduced in order to
avoid bunching at the servers.
In addition, should a server become
unreachable for some time, the poll interval is increased in steps
to 1024s in order to reduce network overhead.
.Pp
In some cases it may not be practical for
.Nm
to run continuously.
A common workaround has been to run the
.Xr ntpdate 8
or
.Xr sntp 8
programs from a
.Xr cron 8
job at designated
times.
However, these programs do not have the crafted signal
processing, error checking or mitigation algorithms of
.Nm .
The
.Fl q
option is intended for this purpose.
Setting this option will cause
.Nm
to exit just after
setting the clock for the first time.
The procedure for initially
setting the clock is the same as in continuous mode; most
applications will probably want to specify the
.Cm iburst
keyword with the
.Ic server
configuration command.
With this
keyword a volley of messages are exchanged to groom the data and
the clock is set in about 10 s.
If nothing is heard after a
couple of minutes, the daemon times out and exits.
After a suitable
period of mourning, the
.Xr ntpdate 8
program will be
retired.
.Pp
When kernel support is available to discipline the clock
frequency, which is the case for stock Solaris, Tru64, Linux and
.Fx ,
a useful feature is available to discipline the clock
frequency.
First,
.Nm
is run in continuous mode with
selected servers in order to measure and record the intrinsic clock
frequency offset in the frequency file.
It may take some hours for
the frequency and offset to settle down.
Then the
.Nm
is
stopped and run in one\-time mode as required.
At each startup, the
frequency is read from the file and initializes the kernel
frequency.
.Ss "Poll Interval Control"
This version of NTP includes an intricate state machine to
reduce the network load while maintaining a quality of
synchronization consistent with the observed jitter and wander.
There are a number of ways to tailor the operation in order enhance
accuracy by reducing the interval or to reduce network overhead by
increasing it.
However, the user is advised to carefully consider
the consequences of changing the poll adjustment range from the
default minimum of 64 s to the default maximum of 1,024 s.
The
default minimum can be changed with the
.Ic tinker
.Cm minpoll
command to a value not less than 16 s.
This value is used for all
configured associations, unless overridden by the
.Cm minpoll
option on the configuration command.
Note that most device drivers
will not operate properly if the poll interval is less than 64 s
and that the broadcast server and manycast client associations will
also use the default, unless overridden.
.Pp
In some cases involving dial up or toll services, it may be
useful to increase the minimum interval to a few tens of minutes
and maximum interval to a day or so.
Under normal operation
conditions, once the clock discipline loop has stabilized the
interval will be increased in steps from the minimum to the
maximum.
However, this assumes the intrinsic clock frequency error
is small enough for the discipline loop correct it.
The capture
range of the loop is 500 PPM at an interval of 64s decreasing by a
factor of two for each doubling of interval.
At a minimum of 1,024
s, for example, the capture range is only 31 PPM.
If the intrinsic
error is greater than this, the drift file
.Pa ntp.drift
will
have to be specially tailored to reduce the residual error below
this limit.
Once this is done, the drift file is automatically
updated once per hour and is available to initialize the frequency
on subsequent daemon restarts.
.Ss "The huff\-n'\-puff Filter"
In scenarios where a considerable amount of data are to be
downloaded or uploaded over telephone modems, timekeeping quality
can be seriously degraded.
This occurs because the differential
delays on the two directions of transmission can be quite large.
In
many cases the apparent time errors are so large as to exceed the
step threshold and a step correction can occur during and after the
data transfer is in progress.
.Pp
The huff\-n'\-puff filter is designed to correct the apparent time
offset in these cases.
It depends on knowledge of the propagation
delay when no other traffic is present.
In common scenarios this
occurs during other than work hours.
The filter maintains a shift
register that remembers the minimum delay over the most recent
interval measured usually in hours.
Under conditions of severe
delay, the filter corrects the apparent offset using the sign of
the offset and the difference between the apparent delay and
minimum delay.
The name of the filter reflects the negative (huff)
and positive (puff) correction, which depends on the sign of the
offset.
.Pp
The filter is activated by the
.Ic tinker
command and
.Cm huffpuff
keyword, as described in
.Xr ntp.conf 5 .
.Sh "ENVIRONMENT"
See \fBOPTION PRESETS\fP for configuration environment variables.
.Sh FILES
.Bl -tag -width /etc/ntp.drift -compact
.It Pa /etc/ntp.conf
the default name of the configuration file
.It Pa /etc/ntp.drift
the default name of the drift file
.It Pa /etc/ntp.keys
the default name of the key file
.El
.Sh "EXIT STATUS"
One of the following exit values will be returned:
.Bl -tag
.It 0 " (EXIT_SUCCESS)"
Successful program execution.
.It 1 " (EXIT_FAILURE)"
The operation failed or the command syntax was not valid.
.It 70 " (EX_SOFTWARE)"
libopts had an internal operational error. Please report
it to autogen\-users@lists.sourceforge.net. Thank you.
.El
.Sh "SEE ALSO"
.Xr ntp.conf 5 ,
.Xr ntpdate 8 ,
.Xr ntpdc 8 ,
.Xr ntpq 8 ,
.Xr sntp 8
.Pp
In addition to the manual pages provided,
comprehensive documentation is available on the world wide web
at
.Li http://www.ntp.org/ .
A snapshot of this documentation is available in HTML format in
.Pa /usr/share/doc/ntp .
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 1)
.%O RFC1059
.Re
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 2)
.%O RFC1119
.Re
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 3)
.%O RFC1305
.Re
.Rs
.%A David L. Mills
.%A J. Martin, Ed.
.%A J. Burbank
.%A W. Kasch
.%T Network Time Protocol Version 4: Protocol and Algorithms Specification
.%O RFC5905
.Re
.Rs
.%A David L. Mills
.%A B. Haberman, Ed.
.%T Network Time Protocol Version 4: Autokey Specification
.%O RFC5906
.Re
.Rs
.%A H. Gerstung
.%A C. Elliott
.%A B. Haberman, Ed.
.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4)
.%O RFC5907
.Re
.Rs
.%A R. Gayraud
.%A B. Lourdelet
.%T Network Time Protocol (NTP) Server Option for DHCPv6
.%O RFC5908
.Re
.Sh "AUTHORS"
The University of Delaware and Network Time Foundation
.Sh "COPYRIGHT"
Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved.
This program is released under the terms of the NTP license, <http://ntp.org/license>.
.Sh BUGS
The
.Nm
utility has gotten rather fat.
While not huge, it has gotten
larger than might be desirable for an elevated\-priority
.Nm
running on a workstation, particularly since many of
the fancy features which consume the space were designed more with
a busy primary server, rather than a high stratum workstation in
mind.
.Pp
Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
.Sh NOTES
Portions of this document came from FreeBSD.
.Pp
This manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP
option definitions.

809
usr.sbin/ntp/doc/ntpdc.8
View File

@ -1,809 +0,0 @@
.Dd August 14 2018
.Dt NTPDC 8 User Commands
.Os
.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.mdoc)
.\"
.\" It has been AutoGen-ed August 14, 2018 at 08:29:43 AM by AutoGen 5.18.5
.\" From the definitions ntpdc-opts.def
.\" and the template file agmdoc-cmd.tpl
.Sh NAME
.Nm ntpdc
.Nd vendor-specific NTPD control program
.Sh SYNOPSIS
.Nm
.\" Mixture of short (flag) options and long options
.Op Fl flags
.Op Fl flag Op Ar value
.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
[ host ...]
.Pp
.Sh DESCRIPTION
.Nm
is deprecated.
Please use
.Xr ntpq 8 instead \- it can do everything
.Nm
used to do, and it does so using a much more sane interface.
.Pp
.Nm
is a utility program used to query
.Xr ntpd 8
about its
current state and to request changes in that state.
It uses NTP mode 7 control message formats described in the source code.
The program may
be run either in interactive mode or controlled using command line
arguments.
Extensive state and statistics information is available
through the
.Nm
interface.
In addition, nearly all the
configuration options which can be specified at startup using
ntpd's configuration file may also be specified at run time using
.Nm .
.Sh "OPTIONS"
.Bl -tag
.It Fl 4 , Fl \-ipv4
Force IPv4 DNS name resolution.
This option must not appear in combination with any of the following options:
ipv6.
.sp
Force DNS resolution of following host names on the command line
to the IPv4 namespace.
.It Fl 6 , Fl \-ipv6
Force IPv6 DNS name resolution.
This option must not appear in combination with any of the following options:
ipv4.
.sp
Force DNS resolution of following host names on the command line
to the IPv6 namespace.
.It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd
run a command and exit.
This option may appear an unlimited number of times.
.sp
The following argument is interpreted as an interactive format command
and is added to the list of commands to be executed on the specified
host(s).
.It Fl d , Fl \-debug\-level
Increase debug verbosity level.
This option may appear an unlimited number of times.
.sp
.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
Set the debug verbosity level.
This option may appear an unlimited number of times.
This option takes an integer number as its argument.
.sp
.It Fl i , Fl \-interactive
Force ntpq to operate in interactive mode.
This option must not appear in combination with any of the following options:
command, listpeers, peers, showpeers.
.sp
Force ntpq to operate in interactive mode. Prompts will be written
to the standard output and commands read from the standard input.
.It Fl l , Fl \-listpeers
Print a list of the peers.
This option must not appear in combination with any of the following options:
command.
.sp
Print a list of the peers known to the server as well as a summary of
their state. This is equivalent to the 'listpeers' interactive command.
.It Fl n , Fl \-numeric
numeric host addresses.
.sp
Output all host addresses in dotted\-quad numeric format rather than
converting to the canonical host names.
.It Fl p , Fl \-peers
Print a list of the peers.
This option must not appear in combination with any of the following options:
command.
.sp
Print a list of the peers known to the server as well as a summary
of their state. This is equivalent to the 'peers' interactive command.
.It Fl s , Fl \-showpeers
Show a list of the peers.
This option must not appear in combination with any of the following options:
command.
.sp
Print a list of the peers known to the server as well as a summary
of their state. This is equivalent to the 'dmpeers' interactive command.
.It Fl \&? , Fl \-help
Display usage information and exit.
.It Fl \&! , Fl \-more\-help
Pass the extended usage information through a pager.
.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP
configuration file listed in the \fBOPTION PRESETS\fP section, below.
The command will exit after updating the config file.
.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
Load options from \fIcfgfile\fP.
The \fIno\-load\-opts\fP form will disable the loading
of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early,
out of order.
.It Fl \-version Op Brq Ar v|c|n
Output version of program and exit. The default mode is `v', a simple
version. The `c' mode will print copyright information and `n' will
print the full copyright notice.
.El
.Sh "OPTION PRESETS"
Any option that is not marked as \fInot presettable\fP may be preset
by loading values from configuration ("RC" or ".INI") file(s) and values from
environment variables named:
.nf
\fBNTPDC_<option\-name>\fP or \fBNTPDC\fP
.fi
.ad
The environmental presets take precedence (are processed later than)
the configuration files.
The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
If any of these are directories, then the file \fI.ntprc\fP
is searched for within those directories.
.Sh USAGE
If one or more request options are included on the command line
when
.Nm
is executed, each of the requests will be sent
to the NTP servers running on each of the hosts given as command
line arguments, or on localhost by default.
If no request options
are given,
.Nm
will attempt to read commands from the
standard input and execute these on the NTP server running on the
first host given on the command line, again defaulting to localhost
when no other host is specified.
The
.Nm
utility will prompt for
commands if the standard input is a terminal device.
.Pp
The
.Nm
utility uses NTP mode 7 packets to communicate with the
NTP server, and hence can be used to query any compatible server on
the network which permits it.
Note that since NTP is a UDP protocol
this communication will be somewhat unreliable, especially over
large distances in terms of network topology.
The
.Nm
utility makes
no attempt to retransmit requests, and will time requests out if
the remote host is not heard from within a suitable timeout
time.
.Pp
The operation of
.Nm
are specific to the particular
implementation of the
.Xr ntpd 8
daemon and can be expected to
work only with this and maybe some previous versions of the daemon.
Requests from a remote
.Nm
utility which affect the
state of the local server must be authenticated, which requires
both the remote program and local server share a common key and key
identifier.
.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.
Specifying a command line option other than
.Fl i
or
.Fl n
will cause the specified query (queries) to be sent to
the indicated host(s) immediately.
Otherwise,
.Nm
will
attempt to read interactive format commands from the standard
input.
.Ss "Interactive Commands"
Interactive format commands consist of a keyword followed by zero
to four arguments.
Only enough characters of the full keyword to
uniquely identify the command need be typed.
The output of a
command is normally sent to the standard output, but optionally the
output of individual commands may be sent to a file by appending a
.Ql \&> ,
followed by a file name, to the command line.
.Pp
A number of interactive format commands are executed entirely
within the
.Nm
utility itself and do not result in NTP
mode 7 requests being sent to a server.
These are described
following.
.Bl -tag -width indent
.It Ic \&? Ar command_keyword
.It Ic help Ar command_keyword
A
.Sq Ic \&?
will print a list of all the command
keywords known to this incarnation of
.Nm .
A
.Sq Ic \&?
followed by a command keyword will print function and usage
information about the command.
This command is probably a better
source of information about
.Xr ntpq 8
than this manual
page.
.It Ic delay Ar milliseconds
Specify a time interval to be added to timestamps included in
requests which require authentication.
This is used to enable
(unreliable) server reconfiguration over long delay network paths
or between machines whose clocks are unsynchronized.
Actually the
server does not now require timestamps in authenticated requests,
so this command may be obsolete.
.It Ic host Ar hostname
Set the host to which future queries will be sent.
Hostname may
be either a host name or a numeric address.
.It Ic hostnames Op Cm yes | Cm no
If
.Cm yes
is specified, host names are printed in
information displays.
If
.Cm no
is specified, numeric
addresses are printed instead.
The default is
.Cm yes ,
unless
modified using the command line
.Fl n
switch.
.It Ic keyid Ar keyid
This command allows the specification of a key number to be
used to authenticate configuration requests.
This must correspond
to a key number the server has been configured to use for this
purpose.
.It Ic quit
Exit
.Nm .
.It Ic passwd
This command prompts you to type in a password (which will not
be echoed) which will be used to authenticate configuration
requests.
The password must correspond to the key configured for
use by the NTP server for this purpose if such requests are to be
successful.
.It Ic timeout Ar milliseconds
Specify a timeout period for responses to server queries.
The
default is about 8000 milliseconds.
Note that since
.Nm
retries each query once after a timeout, the total waiting time for
a timeout will be twice the timeout value set.
.El
.Ss "Control Message Commands"
Query commands result in NTP mode 7 packets containing requests for
information being sent to the server.
These are read\-only commands
in that they make no modification of the server configuration
state.
.Bl -tag -width indent
.It Ic listpeers
Obtains and prints a brief list of the peers for which the
server is maintaining state.
These should include all configured
peer associations as well as those peers whose stratum is such that
they are considered by the server to be possible future
synchronization candidates.
.It Ic peers
Obtains a list of peers for which the server is maintaining
state, along with a summary of that state.
Summary information
includes the address of the remote peer, the local interface
address (0.0.0.0 if a local address has yet to be determined), the
stratum of the remote peer (a stratum of 16 indicates the remote
peer is unsynchronized), the polling interval, in seconds, the
reachability register, in octal, and the current estimated delay,
offset and dispersion of the peer, all in seconds.
.Pp
The character in the left margin indicates the mode this peer
entry is operating in.
A
.Ql \&+
denotes symmetric active, a
.Ql \&\-
indicates symmetric passive, a
.Ql \&=
means the
remote server is being polled in client mode, a
.Ql \&^
indicates that the server is broadcasting to this address, a
.Ql \&~
denotes that the remote peer is sending broadcasts and a
.Ql \&~
denotes that the remote peer is sending broadcasts and a
.Ql \&*
marks the peer the server is currently synchronizing
to.
.Pp
The contents of the host field may be one of four forms.
It may
be a host name, an IP address, a reference clock implementation
name with its parameter or
.Fn REFCLK "implementation_number" "parameter" .
On
.Ic hostnames
.Cm no
only IP\-addresses
will be displayed.
.It Ic dmpeers
A slightly different peer summary list.
Identical to the output
of the
.Ic peers
command, except for the character in the
leftmost column.
Characters only appear beside peers which were
included in the final stage of the clock selection algorithm.
A
.Ql \&.
indicates that this peer was cast off in the falseticker
detection, while a
.Ql \&+
indicates that the peer made it
through.
A
.Ql \&*
denotes the peer the server is currently
synchronizing with.
.It Ic showpeer Ar peer_address Oo Ar ... Oc
Shows a detailed display of the current peer variables for one
or more peers.
Most of these values are described in the NTP
Version 2 specification.
.It Ic pstats Ar peer_address Oo Ar ... Oc
Show per\-peer statistic counters associated with the specified
peer(s).
.It Ic clockstat Ar clock_peer_address Oo Ar ... Oc
Obtain and print information concerning a peer clock.
The
values obtained provide information on the setting of fudge factors
and other clock performance information.
.It Ic kerninfo
Obtain and print kernel phase\-lock loop operating parameters.
This information is available only if the kernel has been specially
modified for a precision timekeeping function.
.It Ic loopinfo Op Cm oneline | Cm multiline
Print the values of selected loop filter variables.
The loop
filter is the part of NTP which deals with adjusting the local
system clock.
The
.Sq offset
is the last offset given to the
loop filter by the packet processing code.
The
.Sq frequency
is the frequency error of the local clock in parts\-per\-million
(ppm).
The
.Sq time_const
controls the stiffness of the
phase\-lock loop and thus the speed at which it can adapt to
oscillator drift.
The
.Sq watchdog timer
value is the number
of seconds which have elapsed since the last sample offset was
given to the loop filter.
The
.Cm oneline
and
.Cm multiline
options specify the format in which this
information is to be printed, with
.Cm multiline
as the
default.
.It Ic sysinfo
Print a variety of system state variables, i.e., state related
to the local server.
All except the last four lines are described
in the NTP Version 3 specification, RFC\-1305.
.Pp
The
.Sq system flags
show various system flags, some of
which can be set and cleared by the
.Ic enable
and
.Ic disable
configuration commands, respectively.
These are
the
.Cm auth ,
.Cm bclient ,
.Cm monitor ,
.Cm pll ,
.Cm pps
and
.Cm stats
flags.
See the
.Xr ntpd 8
documentation for the meaning of these flags.
There
are two additional flags which are read only, the
.Cm kernel_pll
and
.Cm kernel_pps .
These flags indicate
the synchronization status when the precision time kernel
modifications are in use.
The
.Sq kernel_pll
indicates that
the local clock is being disciplined by the kernel, while the
.Sq kernel_pps
indicates the kernel discipline is provided by the PPS
signal.
.Pp
The
.Sq stability
is the residual frequency error remaining
after the system frequency correction is applied and is intended for
maintenance and debugging.
In most architectures, this value will
initially decrease from as high as 500 ppm to a nominal value in
the range .01 to 0.1 ppm.
If it remains high for some time after
starting the daemon, something may be wrong with the local clock,
or the value of the kernel variable
.Va kern.clockrate.tick
may be
incorrect.
.Pp
The
.Sq broadcastdelay
shows the default broadcast delay,
as set by the
.Ic broadcastdelay
configuration command.
.Pp
The
.Sq authdelay
shows the default authentication delay,
as set by the
.Ic authdelay
configuration command.
.It Ic sysstats
Print statistics counters maintained in the protocol
module.
.It Ic memstats
Print statistics counters related to memory allocation
code.
.It Ic iostats
Print statistics counters maintained in the input\-output
module.
.It Ic timerstats
Print statistics counters maintained in the timer/event queue
support code.
.It Ic reslist
Obtain and print the server's restriction list.
This list is
(usually) printed in sorted order and may help to understand how
the restrictions are applied.
.It Ic monlist Op Ar version
Obtain and print traffic counts collected and maintained by the
monitor facility.
The version number should not normally need to be
specified.
.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc
Obtain debugging information for a reference clock driver.
This
information is provided only by some clock drivers and is mostly
undecodable without a copy of the driver source in hand.
.El
.Ss "Runtime Configuration Requests"
All requests which cause state changes in the server are
authenticated by the server using a configured NTP key (the
facility can also be disabled by the server by not configuring a
key).
The key number and the corresponding key must also be made
known to
.Nm .
This can be done using the
.Ic keyid
and
.Ic passwd
commands, the latter of which will prompt at the terminal for a
password to use as the encryption key.
You will also be prompted
automatically for both the key number and password the first time a
command which would result in an authenticated request to the
server is given.
Authentication not only provides verification that
the requester has permission to make such changes, but also gives
an extra degree of protection again transmission errors.
.Pp
Authenticated requests always include a timestamp in the packet
data, which is included in the computation of the authentication
code.
This timestamp is compared by the server to its receive time
stamp.
If they differ by more than a small amount the request is
rejected.
This is done for two reasons.
First, it makes simple
replay attacks on the server, by someone who might be able to
overhear traffic on your LAN, much more difficult.
Second, it makes
it more difficult to request configuration changes to your server
from topologically remote hosts.
While the reconfiguration facility
will work well with a server on the local host, and may work
adequately between time\-synchronized hosts on the same LAN, it will
work very poorly for more distant hosts.
As such, if reasonable
passwords are chosen, care is taken in the distribution and
protection of keys and appropriate source address restrictions are
applied, the run time reconfiguration facility should provide an
adequate level of security.
.Pp
The following commands all make authenticated requests.
.Bl -tag -width indent
.It Xo Ic addpeer Ar peer_address
.Op Ar keyid
.Op Ar version
.Op Cm prefer
.Xc
Add a configured peer association at the given address and
operating in symmetric active mode.
Note that an existing
association with the same peer may be deleted when this command is
executed, or may simply be converted to conform to the new
configuration, as appropriate.
If the optional
.Ar keyid
is a
nonzero integer, all outgoing packets to the remote server will
have an authentication field attached encrypted with this key.
If
the value is 0 (or not given) no authentication will be done.
The
.Ar version
can be 1, 2 or 3 and defaults to 3.
The
.Cm prefer
keyword indicates a preferred peer (and thus will
be used primarily for clock synchronisation if possible).
The
preferred peer also determines the validity of the PPS signal \- if
the preferred peer is suitable for synchronisation so is the PPS
signal.
.It Xo Ic addserver Ar peer_address
.Op Ar keyid
.Op Ar version
.Op Cm prefer
.Xc
Identical to the addpeer command, except that the operating
mode is client.
.It Xo Ic broadcast Ar peer_address
.Op Ar keyid
.Op Ar version
.Op Cm prefer
.Xc
Identical to the addpeer command, except that the operating
mode is broadcast.
In this case a valid key identifier and key are
required.
The
.Ar peer_address
parameter can be the broadcast
address of the local network or a multicast group address assigned
to NTP.
If a multicast address, a multicast\-capable kernel is
required.
.It Ic unconfig Ar peer_address Oo Ar ... Oc
This command causes the configured bit to be removed from the
specified peer(s).
In many cases this will cause the peer
association to be deleted.
When appropriate, however, the
association may persist in an unconfigured mode if the remote peer
is willing to continue on in this fashion.
.It Xo Ic fudge Ar peer_address
.Op Cm time1
.Op Cm time2
.Op Ar stratum
.Op Ar refid
.Xc
This command provides a way to set certain data for a reference
clock.
See the source listing for further information.
.It Xo Ic enable
.Oo
.Cm auth | Cm bclient |
.Cm calibrate | Cm kernel |
.Cm monitor | Cm ntp |
.Cm pps | Cm stats
.Oc
.Xc
.It Xo Ic disable
.Oo
.Cm auth | Cm bclient |
.Cm calibrate | Cm kernel |
.Cm monitor | Cm ntp |
.Cm pps | Cm stats
.Oc
.Xc
These commands operate in the same way as the
.Ic enable
and
.Ic disable
configuration file commands of
.Xr ntpd 8 .
.Bl -tag -width indent
.It Cm auth
Enables the server to synchronize with unconfigured peers only
if the peer has been correctly authenticated using either public key
or private key cryptography.
The default for this flag is enable.
.It Cm bclient
Enables the server to listen for a message from a broadcast or
multicast server, as in the multicastclient command with
default address.
The default for this flag is disable.
.It Cm calibrate
Enables the calibrate feature for reference clocks.
The default for this flag is disable.
.It Cm kernel
Enables the kernel time discipline, if available.
The default for this flag is enable if support is available, otherwise disable.
.It Cm monitor
Enables the monitoring facility.
See the documentation here about the
.Cm monlist
command or further information.
The default for this flag is enable.
.It Cm ntp
Enables time and frequency discipline.
In effect, this switch opens and closes the feedback loop,
which is useful for testing.
The default for this flag is enable.
.It Cm pps
Enables the pulse\-per\-second (PPS) signal when frequency
and time is disciplined by the precision time kernel modifications.
See the
.Qq A Kernel Model for Precision Timekeeping
(available as part of the HTML documentation
provided in
.Pa /usr/share/doc/ntp )
page for further information.
The default for this flag is disable.
.It Cm stats
Enables the statistics facility.
See the
.Sx Monitoring Options
section of
.Xr ntp.conf 5
for further information.
The default for this flag is disable.
.El
.It Xo Ic restrict Ar address Ar mask
.Ar flag Oo Ar ... Oc
.Xc
This command operates in the same way as the
.Ic restrict
configuration file commands of
.Xr ntpd 8 .
.It Xo Ic unrestrict Ar address Ar mask
.Ar flag Oo Ar ... Oc
.Xc
Unrestrict the matching entry from the restrict list.
.It Xo Ic delrestrict Ar address Ar mask
.Op Cm ntpport
.Xc
Delete the matching entry from the restrict list.
.It Ic readkeys
Causes the current set of authentication keys to be purged and
a new set to be obtained by rereading the keys file (which must
have been specified in the
.Xr ntpd 8
configuration file).
This
allows encryption keys to be changed without restarting the
server.
.It Ic trustedkey Ar keyid Oo Ar ... Oc
.It Ic untrustedkey Ar keyid Oo Ar ... Oc
These commands operate in the same way as the
.Ic trustedkey
and
.Ic untrustedkey
configuration file
commands of
.Xr ntpd 8 .
.It Ic authinfo
Returns information concerning the authentication module,
including known keys and counts of encryptions and decryptions
which have been done.
.It Ic traps
Display the traps set in the server.
See the source listing for
further information.
.It Xo Ic addtrap Ar address
.Op Ar port
.Op Ar interface
.Xc
Set a trap for asynchronous messages.
See the source listing
for further information.
.It Xo Ic clrtrap Ar address
.Op Ar port
.Op Ar interface
.Xc
Clear a trap for asynchronous messages.
See the source listing
for further information.
.It Ic reset
Clear the statistics counters in various modules of the server.
See the source listing for further information.
.El
.Sh "ENVIRONMENT"
See \fBOPTION PRESETS\fP for configuration environment variables.
.Sh "FILES"
See \fBOPTION PRESETS\fP for configuration files.
.Sh "EXIT STATUS"
One of the following exit values will be returned:
.Bl -tag
.It 0 " (EXIT_SUCCESS)"
Successful program execution.
.It 1 " (EXIT_FAILURE)"
The operation failed or the command syntax was not valid.
.It 66 " (EX_NOINPUT)"
A specified configuration file could not be loaded.
.It 70 " (EX_SOFTWARE)"
libopts had an internal operational error. Please report
it to autogen\-users@lists.sourceforge.net. Thank you.
.El
.Sh "SEE ALSO"
.Xr ntp.conf 5 ,
.Xr ntpd 8
.Rs
.%A David L. Mills
.%T Network Time Protocol (Version 3)
.%O RFC1305
.Re
.Sh AUTHORS
The formatting directives in this document came from FreeBSD.
.Sh "COPYRIGHT"
Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved.
This program is released under the terms of the NTP license, <http://ntp.org/license>.
.Sh BUGS
The
.Nm
utility is a crude hack.
Much of the information it shows is
deadly boring and could only be loved by its implementer.
The
program was designed so that new (and temporary) features were easy
to hack in, at great expense to the program's ease of use.
Despite
this, the program is occasionally useful.
.Pp
Please report bugs to http://bugs.ntp.org .
.Pp
Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
.Sh "NOTES"
This manual page was \fIAutoGen\fP\-erated from the \fBntpdc\fP
option definitions.

1055
usr.sbin/ntp/doc/ntpq.8
View File

File diff suppressed because it is too large Load Diff

317
usr.sbin/ntp/doc/sntp.8
View File

@ -1,317 +0,0 @@
.Dd August 14 2018
.Dt SNTP 8 User Commands
.Os
.\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc)
.\"
.\" It has been AutoGen-ed August 14, 2018 at 08:27:40 AM by AutoGen 5.18.5
.\" From the definitions sntp-opts.def
.\" and the template file agmdoc-cmd.tpl
.Sh NAME
.Nm sntp
.Nd reference Simple Network Time Protocol client
.Sh SYNOPSIS
.Nm
.\" Mixture of short (flag) options and long options
.Op Fl flags
.Op Fl flag Op Ar value
.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
[ hostname\-or\-IP ...]
.Pp
.Sh DESCRIPTION
.Nm
can be used as an SNTP client to query a NTP or SNTP server and either display
the time or set the local system's time (given suitable privilege). It can be
run as an interactive command or from a
.Ic cron
job.
NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
are defined and described by RFC 5905.
.Pp
The default is to write the estimated correct local date and time (i.e. not
UTC) to the standard output in a format like:
.Ic "'1996\-10\-15 20:17:25.123 (+0800) +4.567 +/\- 0.089 [host] IP sN'"
where the
.Ic "'(+0800)'"
means that to get to UTC from the reported local time one must
add 8 hours and 0 minutes,
the
.Ic "'+4.567'"
indicates the local clock is 4.567 seconds behind the correct time
(so 4.567 seconds must be added to the local clock to get it to be correct).
Note that the number of decimals printed for this value will change
based on the reported precision of the server.
.Ic "'+/\- 0.089'"
is the reported
.Em synchronization distance
(in seconds), which represents the maximum error due to all causes.
If the server does not report valid data needed to calculate the
synchronization distance, this will be reported as
.Ic "'+/\- ?'" .
If the
.Em host
is different from the
.Em IP ,
both will be displayed.
Otherwise, only the
.Em IP
is displayed.
Finally, the
.Em stratum
of the host is reported
and the leap indicator is decoded and displayed.
.Sh "OPTIONS"
.Bl -tag
.It Fl 4 , Fl \-ipv4
Force IPv4 DNS name resolution.
This option must not appear in combination with any of the following options:
ipv6.
.sp
Force DNS resolution of the following host names on the command line
to the IPv4 namespace.
.It Fl 6 , Fl \-ipv6
Force IPv6 DNS name resolution.
This option must not appear in combination with any of the following options:
ipv4.
.sp
Force DNS resolution of the following host names on the command line
to the IPv6 namespace.
.It Fl a Ar auth\-keynumber , Fl \-authentication Ns = Ns Ar auth\-keynumber
Enable authentication with the key \fBauth\-keynumber\fP.
This option takes an integer number as its argument.
.sp
Enable authentication using the key specified in this option's
argument. The argument of this option is the \fBkeyid\fP, a
number specified in the \fBkeyfile\fP as this key's identifier.
See the \fBkeyfile\fP option (\fB\-k\fP) for more details.
.It Fl b Ar broadcast\-address , Fl \-broadcast Ns = Ns Ar broadcast\-address
Listen to the address specified for broadcast time sync.
This option may appear an unlimited number of times.
.sp
If specified \fBsntp\fP will listen to the specified address
for NTP broadcasts. The default maximum wait time
can (and probably should) be modified with \fB\-t\fP.
.It Fl c Ar host\-name , Fl \-concurrent Ns = Ns Ar host\-name
Concurrently query all IPs returned for host\-name.
This option may appear an unlimited number of times.
.sp
Requests from an NTP "client" to a "server" should never be sent
more rapidly than one every 2 seconds. By default, any IPs returned
as part of a DNS lookup are assumed to be for a single instance of
\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs
one after another, with a 2\-second gap in between each query.
.sp
The \fB\-c\fP or \fB\-\-concurrent\fP flag says that any IPs
returned for the DNS lookup of the supplied host\-name are on
different machines, so we can send concurrent queries.
.It Fl d , Fl \-debug\-level
Increase debug verbosity level.
This option may appear an unlimited number of times.
.sp
.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
Set the debug verbosity level.
This option may appear an unlimited number of times.
This option takes an integer number as its argument.
.sp
.It Fl g Ar milliseconds , Fl \-gap Ns = Ns Ar milliseconds
The gap (in milliseconds) between time requests.
This option takes an integer number as its argument.
The default
.Ar milliseconds
for this option is:
.ti +4
50
.sp
Since we're only going to use the first valid response we get and
there is benefit to specifying a good number of servers to query,
separate the queries we send out by the specified number of
milliseconds.
.It Fl K Ar file\-name , Fl \-kod Ns = Ns Ar file\-name
KoD history filename.
The default
.Ar file\-name
for this option is:
.ti +4
/var/db/ntp\-kod
.sp
Specifies the filename to be used for the persistent history of KoD
responses received from servers. If the file does not exist, a
warning message will be displayed. The file will not be created.
.It Fl k Ar file\-name , Fl \-keyfile Ns = Ns Ar file\-name
Look in this file for the key specified with \fB\-a\fP.
The default
.Ar file\-name
for this option is:
.ti +4
/etc/ntp.keys
.sp
This option specifies the keyfile.
\fBsntp\fP will search for the key specified with \fB\-a\fP
\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more
information.
.It Fl l Ar file\-name , Fl \-logfile Ns = Ns Ar file\-name
Log to specified logfile.
.sp
This option causes the client to write log messages to the specified
\fIlogfile\fP.
.It Fl M Ar number , Fl \-steplimit Ns = Ns Ar number
Adjustments less than \fBsteplimit\fP msec will be slewed.
This option takes an integer number as its argument.
The value of
.Ar number
is constrained to being:
.in +4
.nf
.na
greater than or equal to 0
.fi
.in -4
.sp
If the time adjustment is less than \fIsteplimit\fP milliseconds,
slew the amount using \fBadjtime(2)\fP. Otherwise, step the
correction using \fBsettimeofday(2)\fP. The default value is 0,
which means all adjustments will be stepped. This is a feature, as
different situations demand different values.
.It Fl o Ar number , Fl \-ntpversion Ns = Ns Ar number
Send \fBint\fP as our NTP protocol version.
This option takes an integer number as its argument.
The value of
.Ar number
is constrained to being:
.in +4
.nf
.na
in the range 0 through 7
.fi
.in -4
The default
.Ar number
for this option is:
.ti +4
4
.sp
When sending requests to a remote server, tell them we are running
NTP protocol version \fIntpversion\fP .
.It Fl r , Fl \-usereservedport
Use the NTP Reserved Port (port 123).
.sp
Use port 123, which is reserved for NTP, for our network
communications.
.It Fl S , Fl \-step
OK to 'step' the time with \fBsettimeofday(2)\fP.
.sp
.It Fl s , Fl \-slew
OK to 'slew' the time with \fBadjtime(2)\fP.
.sp
.It Fl t Ar seconds , Fl \-timeout Ns = Ns Ar seconds
The number of seconds to wait for responses.
This option takes an integer number as its argument.
The default
.Ar seconds
for this option is:
.ti +4
5
.sp
When waiting for a reply, \fBsntp\fP will wait the number
of seconds specified before giving up. The default should be
more than enough for a unicast response. If \fBsntp\fP is
only waiting for a broadcast response a longer timeout is
likely needed.
.It Fl \-wait , Fl \-no\-wait
Wait for pending replies (if not setting the time).
The \fIno\-wait\fP form will disable the option.
This option is enabled by default.
.sp
If we are not setting the time, wait for all pending responses.
.It Fl \&? , Fl \-help
Display usage information and exit.
.It Fl \&! , Fl \-more\-help
Pass the extended usage information through a pager.
.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP
configuration file listed in the \fBOPTION PRESETS\fP section, below.
The command will exit after updating the config file.
.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
Load options from \fIcfgfile\fP.
The \fIno\-load\-opts\fP form will disable the loading
of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early,
out of order.
.It Fl \-version Op Brq Ar v|c|n
Output version of program and exit. The default mode is `v', a simple
version. The `c' mode will print copyright information and `n' will
print the full copyright notice.
.El
.Sh "OPTION PRESETS"
Any option that is not marked as \fInot presettable\fP may be preset
by loading values from configuration ("RC" or ".INI") file(s) and values from
environment variables named:
.nf
\fBSNTP_<option\-name>\fP or \fBSNTP\fP
.fi
.ad
The environmental presets take precedence (are processed later than)
the configuration files.
The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
If any of these are directories, then the file \fI.ntprc\fP
is searched for within those directories.
.Sh USAGE
.Bl -tag -width indent
.It Li "sntp ntpserver.somewhere"
is the simplest use of this program
and can be run as an unprivileged command
to check the current time and error in the local clock.
.It Li "sntp \-Ss \-M 128 ntpserver.somewhere"
With suitable privilege,
run as a command
or from a
.Xr cron 8
job,
.Ic "sntp \-Ss \-M 128 ntpserver.somewhere"
will request the time from the server,
and if that server reports that it is synchronized
then if the offset adjustment is less than 128 milliseconds
the correction will be slewed,
and if the correction is more than 128 milliseconds
the correction will be stepped.
.It Li "sntp \-S ntpserver.somewhere"
With suitable privilege,
run as a command
or from a
.Xr cron 8
job,
.Ic "sntp \-S ntpserver.somewhere"
will set (step) the local clock from a synchronized specified server,
like the (deprecated)
.Xr ntpdate 8 ,
or
.Xr rdate 8
commands.
.El
.Sh "ENVIRONMENT"
See \fBOPTION PRESETS\fP for configuration environment variables.
.Sh "FILES"
See \fBOPTION PRESETS\fP for configuration files.
.Sh "EXIT STATUS"
One of the following exit values will be returned:
.Bl -tag
.It 0 " (EXIT_SUCCESS)"
Successful program execution.
.It 1 " (EXIT_FAILURE)"
The operation failed or the command syntax was not valid.
.It 66 " (EX_NOINPUT)"
A specified configuration file could not be loaded.
.It 70 " (EX_SOFTWARE)"
libopts had an internal operational error. Please report
it to autogen\-users@lists.sourceforge.net. Thank you.
.El
.Sh AUTHORS
.An "Johannes Maximilian Kuehn"
.An "Harlan Stenn"
.An "Dave Hart"
.Sh "COPYRIGHT"
Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved.
This program is released under the terms of the NTP license, <http://ntp.org/license>.
.Sh "BUGS"
Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
.Sh "NOTES"
This manual page was \fIAutoGen\fP\-erated from the \fBsntp\fP
option definitions.