767173cec2
Update 4.2.8p14 --> 4.2.8p15 Summary: Systems that use a CMAC algorithm in ntp.keys will not release a bit of memory on each packet that uses a CMAC keyid, eventually causing ntpd to run out of memory and fail. The CMAC cleanup from https://bugs.ntp.org/3447, part of ntp-4.2.8p11, introduced a bug whereby the CMAC data structure was no longer completely removed. MFC after: 3 days Security: NTP Bug 3661
363 lines
12 KiB
Groff
363 lines
12 KiB
Groff
.de1 NOP
|
|
. it 1 an-trap
|
|
. if \\n[.$] \,\\$*\/
|
|
..
|
|
.ie t \
|
|
.ds B-Font [CB]
|
|
.ds I-Font [CI]
|
|
.ds R-Font [CR]
|
|
.el \
|
|
.ds B-Font B
|
|
.ds I-Font I
|
|
.ds R-Font R
|
|
.TH sntp @SNTP_MS@ "23 Jun 2020" "4.2.8p15" "User Commands"
|
|
.\"
|
|
.\" EDIT THIS FILE WITH CAUTION (in-mem file)
|
|
.\"
|
|
.\" It has been AutoGen-ed June 23, 2020 at 02:19:38 AM by AutoGen 5.18.5
|
|
.\" From the definitions sntp-opts.def
|
|
.\" and the template file agman-cmd.tpl
|
|
.SH NAME
|
|
\f\*[B-Font]sntp\fP
|
|
\- standard Simple Network Time Protocol client program
|
|
.SH SYNOPSIS
|
|
\f\*[B-Font]sntp\fP
|
|
.\" Mixture of short (flag) options and long options
|
|
[\f\*[B-Font]\-flags\f[]]
|
|
[\f\*[B-Font]\-flag\f[] [\f\*[I-Font]value\f[]]]
|
|
[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
|
|
[ hostname-or-IP ...]
|
|
.sp \n(Ppu
|
|
.ne 2
|
|
|
|
.SH DESCRIPTION
|
|
\f\*[B-Font]sntp\fP
|
|
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
|
|
\f\*[B-Font]cron\f[]
|
|
job.
|
|
NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
|
|
are defined and described by RFC 5905.
|
|
.sp \n(Ppu
|
|
.ne 2
|
|
|
|
The default is to write the estimated correct local date and time (i.e. not
|
|
UTC) to the standard output in a format like:
|
|
\f\*[B-Font]'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'\f[]
|
|
where the
|
|
\f\*[B-Font]'(+0800)'\f[]
|
|
means that to get to UTC from the reported local time one must
|
|
add 8 hours and 0 minutes,
|
|
the
|
|
\f\*[B-Font]'+4.567'\f[]
|
|
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.
|
|
\f\*[B-Font]'+/- 0.089'\f[]
|
|
is the reported
|
|
\fIsynchronization\f[] \fIdistance\f[]
|
|
(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
|
|
\f\*[B-Font]'+/- ?'\f[].
|
|
If the
|
|
\fIhost\f[]
|
|
is different from the
|
|
\fIIP\f[],
|
|
both will be displayed.
|
|
Otherwise, only the
|
|
\fIIP\f[]
|
|
is displayed.
|
|
Finally, the
|
|
\fIstratum\f[]
|
|
of the host is reported
|
|
and the leap indicator is decoded and displayed.
|
|
.SH "OPTIONS"
|
|
.TP
|
|
.NOP \f\*[B-Font]\-4\f[], \f\*[B-Font]\-\-ipv4\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-6\f[], \f\*[B-Font]\-\-ipv6\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-a\f[] \f\*[I-Font]auth\-keynumber\f[], \f\*[B-Font]\-\-authentication\f[]=\f\*[I-Font]auth\-keynumber\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]broadcast\-address\f[], \f\*[B-Font]\-\-broadcast\f[]=\f\*[I-Font]broadcast\-address\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-c\f[] \f\*[I-Font]host\-name\f[], \f\*[B-Font]\-\-concurrent\f[]=\f\*[I-Font]host\-name\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-d\f[], \f\*[B-Font]\-\-debug\-level\f[]
|
|
Increase debug verbosity level.
|
|
This option may appear an unlimited number of times.
|
|
.sp
|
|
.TP
|
|
.NOP \f\*[B-Font]\-D\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-set\-debug\-level\f[]=\f\*[I-Font]number\f[]
|
|
Set the debug verbosity level.
|
|
This option may appear an unlimited number of times.
|
|
This option takes an integer number as its argument.
|
|
.sp
|
|
.TP
|
|
.NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]milliseconds\f[], \f\*[B-Font]\-\-gap\f[]=\f\*[I-Font]milliseconds\f[]
|
|
The gap (in milliseconds) between time requests.
|
|
This option takes an integer number as its argument.
|
|
The default
|
|
\f\*[I-Font]milliseconds\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-K\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-kod\f[]=\f\*[I-Font]file\-name\f[]
|
|
KoD history filename.
|
|
The default
|
|
\f\*[I-Font]file\-name\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-k\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-keyfile\f[]=\f\*[I-Font]file\-name\f[]
|
|
Look in this file for the key specified with \fB-a\fP.
|
|
The default
|
|
\f\*[I-Font]file\-name\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]file\-name\f[], \f\*[B-Font]\-\-logfile\f[]=\f\*[I-Font]file\-name\f[]
|
|
Log to specified logfile.
|
|
.sp
|
|
This option causes the client to write log messages to the specified
|
|
\fIlogfile\fP.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-M\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-steplimit\f[]=\f\*[I-Font]number\f[]
|
|
Adjustments less than \fBsteplimit\fP msec will be slewed.
|
|
This option takes an integer number as its argument.
|
|
The value of
|
|
\f\*[I-Font]number\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]number\f[], \f\*[B-Font]\-\-ntpversion\f[]=\f\*[I-Font]number\f[]
|
|
Send \fBint\fP as our NTP protocol version.
|
|
This option takes an integer number as its argument.
|
|
The value of
|
|
\f\*[I-Font]number\f[]
|
|
is constrained to being:
|
|
.in +4
|
|
.nf
|
|
.na
|
|
in the range 0 through 7
|
|
.fi
|
|
.in -4
|
|
The default
|
|
\f\*[I-Font]number\f[]
|
|
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 .
|
|
.TP
|
|
.NOP \f\*[B-Font]\-r\f[], \f\*[B-Font]\-\-usereservedport\f[]
|
|
Use the NTP Reserved Port (port 123).
|
|
.sp
|
|
Use port 123, which is reserved for NTP, for our network
|
|
communications.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-S\f[], \f\*[B-Font]\-\-step\f[]
|
|
OK to 'step' the time with \fBsettimeofday(2)\fP.
|
|
.sp
|
|
.TP
|
|
.NOP \f\*[B-Font]\-s\f[], \f\*[B-Font]\-\-slew\f[]
|
|
OK to 'slew' the time with \fBadjtime(2)\fP.
|
|
.sp
|
|
.TP
|
|
.NOP \f\*[B-Font]\-t\f[] \f\*[I-Font]seconds\f[], \f\*[B-Font]\-\-timeout\f[]=\f\*[I-Font]seconds\f[]
|
|
The number of seconds to wait for responses.
|
|
This option takes an integer number as its argument.
|
|
The default
|
|
\f\*[I-Font]seconds\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-\-wait\f[], \f\*[B-Font]\- Fl \-no\-wait\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-\&?\f[], \f\*[B-Font]\-\-help\f[]
|
|
Display usage information and exit.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
|
|
Pass the extended usage information through a pager.
|
|
.TP
|
|
.NOP \f\*[B-Font]\->\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-<\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
|
|
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.
|
|
.TP
|
|
.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]
|
|
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.
|
|
.PP
|
|
.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
|
|
.TP 7
|
|
.NOP \f[C]sntp ntpserver.somewhere\f[]
|
|
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.
|
|
.TP 7
|
|
.NOP \f[C]sntp \-Ss \-M 128 ntpserver.somewhere\f[]
|
|
With suitable privilege,
|
|
run as a command
|
|
or from a
|
|
\fCcron\f[]\fR(8)\f[]
|
|
job,
|
|
\f\*[B-Font]sntp \-Ss \-M 128 ntpserver.somewhere\f[]
|
|
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.
|
|
.TP 7
|
|
.NOP \f[C]sntp \-S ntpserver.somewhere\f[]
|
|
With suitable privilege,
|
|
run as a command
|
|
or from a
|
|
\fCcron\f[]\fR(8)\f[]
|
|
job,
|
|
\f\*[B-Font]sntp \-S ntpserver.somewhere\f[]
|
|
will set (step) the local clock from a synchronized specified server,
|
|
like the (deprecated)
|
|
\fCntpdate\f[]\fR(@NTPDATE_MS@)\f[],
|
|
or
|
|
\fCrdate\f[]\fR(8)\f[]
|
|
commands.
|
|
.PP
|
|
.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:
|
|
.TP
|
|
.NOP 0 " (EXIT_SUCCESS)"
|
|
Successful program execution.
|
|
.TP
|
|
.NOP 1 " (EXIT_FAILURE)"
|
|
The operation failed or the command syntax was not valid.
|
|
.TP
|
|
.NOP 66 " (EX_NOINPUT)"
|
|
A specified configuration file could not be loaded.
|
|
.TP
|
|
.NOP 70 " (EX_SOFTWARE)"
|
|
libopts had an internal operational error. Please report
|
|
it to autogen-users@lists.sourceforge.net. Thank you.
|
|
.PP
|
|
.SH AUTHORS
|
|
.NOP "Johannes Maximilian Kuehn"
|
|
.br
|
|
.NOP "Harlan Stenn"
|
|
.br
|
|
.NOP "Dave Hart"
|
|
.br
|
|
.SH "COPYRIGHT"
|
|
Copyright (C) 1992-2020 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.
|