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
431 lines
15 KiB
Plaintext
431 lines
15 KiB
Plaintext
@node sntp Invocation
|
|
@section Invoking sntp
|
|
@pindex sntp
|
|
@cindex standard Simple Network Time Protocol client program
|
|
@ignore
|
|
#
|
|
# EDIT THIS FILE WITH CAUTION (invoke-sntp.texi)
|
|
#
|
|
# It has been AutoGen-ed June 23, 2020 at 02:19:36 AM by AutoGen 5.18.5
|
|
# From the definitions sntp-opts.def
|
|
# and the template file agtexi-cmd.tpl
|
|
@end ignore
|
|
|
|
|
|
|
|
@code{sntp}
|
|
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
|
|
@code{cron}
|
|
job.
|
|
|
|
NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
|
|
are defined and described by RFC 5905.
|
|
|
|
|
|
The default is to write the estimated correct local date and time (i.e. not
|
|
UTC) to the standard output in a format like:
|
|
|
|
@code{'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'}
|
|
|
|
where the
|
|
@code{'(+0800)'}
|
|
means that to get to UTC from the reported local time one must
|
|
add 8 hours and 0 minutes,
|
|
the
|
|
@code{'+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.
|
|
@code{'+/- 0.089'}
|
|
is the reported
|
|
@emph{synchronization} @emph{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
|
|
@code{'+/- ?'}.
|
|
If the
|
|
@emph{host}
|
|
is different from the
|
|
@emph{IP},
|
|
both will be displayed.
|
|
Otherwise, only the
|
|
@emph{IP}
|
|
is displayed.
|
|
Finally, the
|
|
@emph{stratum}
|
|
of the host is reported
|
|
and the leap indicator is decoded and displayed.
|
|
|
|
This section was generated by @strong{AutoGen},
|
|
using the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program.
|
|
This software is released under the NTP license, <http://ntp.org/license>.
|
|
|
|
@menu
|
|
* sntp usage:: sntp help/usage (@option{--help})
|
|
* sntp ipv4:: ipv4 option (-4)
|
|
* sntp ipv6:: ipv6 option (-6)
|
|
* sntp authentication:: authentication option (-a)
|
|
* sntp broadcast:: broadcast option (-b)
|
|
* sntp concurrent:: concurrent option (-c)
|
|
* sntp gap:: gap option (-g)
|
|
* sntp kod:: kod option (-K)
|
|
* sntp keyfile:: keyfile option (-k)
|
|
* sntp logfile:: logfile option (-l)
|
|
* sntp steplimit:: steplimit option (-M)
|
|
* sntp ntpversion:: ntpversion option (-o)
|
|
* sntp usereservedport:: usereservedport option (-r)
|
|
* sntp timeout:: timeout option (-t)
|
|
* sntp wait:: wait option
|
|
* sntp config:: presetting/configuring sntp
|
|
* sntp exit status:: exit status
|
|
* sntp Usage:: Usage
|
|
* sntp Authors:: Authors
|
|
@end menu
|
|
|
|
@node sntp usage
|
|
@subsection sntp help/usage (@option{--help})
|
|
@cindex sntp help
|
|
|
|
This is the automatically generated usage text for sntp.
|
|
|
|
The text printed is the same whether selected with the @code{help} option
|
|
(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
|
|
the usage text by passing it through a pager program.
|
|
@code{more-help} is disabled on platforms without a working
|
|
@code{fork(2)} function. The @code{PAGER} environment variable is
|
|
used to select the program, defaulting to @file{more}. Both will exit
|
|
with a status code of 0.
|
|
|
|
@exampleindent 0
|
|
@example
|
|
sntp - standard Simple Network Time Protocol client program - Ver. 4.2.8p15
|
|
Usage: sntp [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \
|
|
[ hostname-or-IP ...]
|
|
Flg Arg Option-Name Description
|
|
-4 no ipv4 Force IPv4 DNS name resolution
|
|
- prohibits the option 'ipv6'
|
|
-6 no ipv6 Force IPv6 DNS name resolution
|
|
- prohibits the option 'ipv4'
|
|
-a Num authentication Enable authentication with the key auth-keynumber
|
|
-b Str broadcast Listen to the address specified for broadcast time sync
|
|
- may appear multiple times
|
|
-c Str concurrent Concurrently query all IPs returned for host-name
|
|
- may appear multiple times
|
|
-d no debug-level Increase debug verbosity level
|
|
- may appear multiple times
|
|
-D Num set-debug-level Set the debug verbosity level
|
|
- may appear multiple times
|
|
-g Num gap The gap (in milliseconds) between time requests
|
|
-K Fil kod KoD history filename
|
|
-k Fil keyfile Look in this file for the key specified with -a
|
|
-l Fil logfile Log to specified logfile
|
|
-M Num steplimit Adjustments less than steplimit msec will be slewed
|
|
- it must be in the range:
|
|
greater than or equal to 0
|
|
-o Num ntpversion Send int as our NTP protocol version
|
|
- it must be in the range:
|
|
0 to 7
|
|
-r no usereservedport Use the NTP Reserved Port (port 123)
|
|
-S no step OK to 'step' the time with settimeofday(2)
|
|
-s no slew OK to 'slew' the time with adjtime(2)
|
|
-t Num timeout The number of seconds to wait for responses
|
|
no wait Wait for pending replies (if not setting the time)
|
|
- disabled as '--no-wait'
|
|
- enabled by default
|
|
opt version output version information and exit
|
|
-? no help display extended usage information and exit
|
|
-! no more-help extended usage information passed thru pager
|
|
-> opt save-opts save the option state to a config file
|
|
-< Str load-opts load options from a config file
|
|
- disabled as '--no-load-opts'
|
|
- may appear multiple times
|
|
|
|
Options are specified by doubled hyphens and their name or by a single
|
|
hyphen and the flag character.
|
|
|
|
|
|
The following option preset mechanisms are supported:
|
|
- reading file $HOME/.ntprc
|
|
- reading file ./.ntprc
|
|
- examining environment variables named SNTP_*
|
|
|
|
Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
|
|
@end example
|
|
@exampleindent 4
|
|
|
|
@node sntp ipv4
|
|
@subsection ipv4 option (-4)
|
|
@cindex sntp-ipv4
|
|
|
|
This is the ``force ipv4 dns name resolution'' option.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
must not appear in combination with any of the following options:
|
|
ipv6.
|
|
@end itemize
|
|
|
|
Force DNS resolution of the following host names on the command line
|
|
to the IPv4 namespace.
|
|
@node sntp ipv6
|
|
@subsection ipv6 option (-6)
|
|
@cindex sntp-ipv6
|
|
|
|
This is the ``force ipv6 dns name resolution'' option.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
must not appear in combination with any of the following options:
|
|
ipv4.
|
|
@end itemize
|
|
|
|
Force DNS resolution of the following host names on the command line
|
|
to the IPv6 namespace.
|
|
@node sntp authentication
|
|
@subsection authentication option (-a)
|
|
@cindex sntp-authentication
|
|
|
|
This is the ``enable authentication with the key @var{auth-keynumber}'' option.
|
|
This option takes a number argument @file{auth-keynumber}.
|
|
Enable authentication using the key specified in this option's
|
|
argument. The argument of this option is the @option{keyid}, a
|
|
number specified in the @option{keyfile} as this key's identifier.
|
|
See the @option{keyfile} option (@option{-k}) for more details.
|
|
@node sntp broadcast
|
|
@subsection broadcast option (-b)
|
|
@cindex sntp-broadcast
|
|
|
|
This is the ``listen to the address specified for broadcast time sync'' option.
|
|
This option takes a string argument @file{broadcast-address}.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
may appear an unlimited number of times.
|
|
@end itemize
|
|
|
|
If specified @code{sntp} will listen to the specified address
|
|
for NTP broadcasts. The default maximum wait time
|
|
can (and probably should) be modified with @option{-t}.
|
|
@node sntp concurrent
|
|
@subsection concurrent option (-c)
|
|
@cindex sntp-concurrent
|
|
|
|
This is the ``concurrently query all ips returned for host-name'' option.
|
|
This option takes a string argument @file{host-name}.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
may appear an unlimited number of times.
|
|
@end itemize
|
|
|
|
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
|
|
@code{ntpd}, and therefore @code{sntp} will send queries to these IPs
|
|
one after another, with a 2-second gap in between each query.
|
|
|
|
The @option{-c} or @option{--concurrent} 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.
|
|
@node sntp gap
|
|
@subsection gap option (-g)
|
|
@cindex sntp-gap
|
|
|
|
This is the ``the gap (in milliseconds) between time requests'' option.
|
|
This option takes a number argument @file{milliseconds}.
|
|
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.
|
|
@node sntp kod
|
|
@subsection kod option (-K)
|
|
@cindex sntp-kod
|
|
|
|
This is the ``kod history filename'' option.
|
|
This option takes a file argument @file{file-name}.
|
|
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.
|
|
@node sntp keyfile
|
|
@subsection keyfile option (-k)
|
|
@cindex sntp-keyfile
|
|
|
|
This is the ``look in this file for the key specified with @option{-a}'' option.
|
|
This option takes a file argument @file{file-name}.
|
|
This option specifies the keyfile.
|
|
@code{sntp} will search for the key specified with @option{-a}
|
|
@file{keyno} in this file. See @command{ntp.keys(5)} for more
|
|
information.
|
|
@node sntp logfile
|
|
@subsection logfile option (-l)
|
|
@cindex sntp-logfile
|
|
|
|
This is the ``log to specified logfile'' option.
|
|
This option takes a file argument @file{file-name}.
|
|
This option causes the client to write log messages to the specified
|
|
@file{logfile}.
|
|
@node sntp steplimit
|
|
@subsection steplimit option (-M)
|
|
@cindex sntp-steplimit
|
|
|
|
This is the ``adjustments less than @var{steplimit} msec will be slewed'' option.
|
|
This option takes a number argument.
|
|
If the time adjustment is less than @file{steplimit} milliseconds,
|
|
slew the amount using @command{adjtime(2)}. Otherwise, step the
|
|
correction using @command{settimeofday(2)}. The default value is 0,
|
|
which means all adjustments will be stepped. This is a feature, as
|
|
different situations demand different values.
|
|
@node sntp ntpversion
|
|
@subsection ntpversion option (-o)
|
|
@cindex sntp-ntpversion
|
|
|
|
This is the ``send @var{int} as our ntp protocol version'' option.
|
|
This option takes a number argument.
|
|
When sending requests to a remote server, tell them we are running
|
|
NTP protocol version @file{ntpversion} .
|
|
@node sntp usereservedport
|
|
@subsection usereservedport option (-r)
|
|
@cindex sntp-usereservedport
|
|
|
|
This is the ``use the ntp reserved port (port 123)'' option.
|
|
Use port 123, which is reserved for NTP, for our network
|
|
communications.
|
|
@node sntp timeout
|
|
@subsection timeout option (-t)
|
|
@cindex sntp-timeout
|
|
|
|
This is the ``the number of seconds to wait for responses'' option.
|
|
This option takes a number argument @file{seconds}.
|
|
When waiting for a reply, @code{sntp} will wait the number
|
|
of seconds specified before giving up. The default should be
|
|
more than enough for a unicast response. If @code{sntp} is
|
|
only waiting for a broadcast response a longer timeout is
|
|
likely needed.
|
|
@node sntp wait
|
|
@subsection wait option
|
|
@cindex sntp-wait
|
|
|
|
This is the ``wait for pending replies (if not setting the time)'' option.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
can be disabled with --no-wait.
|
|
@item
|
|
It is enabled by default.
|
|
@end itemize
|
|
|
|
If we are not setting the time, wait for all pending responses.
|
|
|
|
|
|
@node sntp config
|
|
@subsection presetting/configuring sntp
|
|
|
|
Any option that is not marked as @i{not presettable} may be preset by
|
|
loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{SNTP} and @code{SNTP_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
|
|
the options listed above in upper case and segmented with underscores.
|
|
The @code{SNTP} variable will be tokenized and parsed like
|
|
the command line. The remaining variables are tested for existence and their
|
|
values are treated like option arguments.
|
|
|
|
|
|
@noindent
|
|
@code{libopts} will search in 2 places for configuration files:
|
|
@itemize @bullet
|
|
@item
|
|
$HOME
|
|
@item
|
|
$PWD
|
|
@end itemize
|
|
The environment variables @code{HOME}, and @code{PWD}
|
|
are expanded and replaced when @file{sntp} runs.
|
|
For any of these that are plain files, they are simply processed.
|
|
For any that are directories, then a file named @file{.ntprc} is searched for
|
|
within that directory and processed.
|
|
|
|
Configuration files may be in a wide variety of formats.
|
|
The basic format is an option name followed by a value (argument) on the
|
|
same line. Values may be separated from the option name with a colon,
|
|
equal sign or simply white space. Values may be continued across multiple
|
|
lines by escaping the newline with a backslash.
|
|
|
|
Multiple programs may also share the same initialization file.
|
|
Common options are collected at the top, followed by program specific
|
|
segments. The segments are separated by lines like:
|
|
@example
|
|
[SNTP]
|
|
@end example
|
|
@noindent
|
|
or by
|
|
@example
|
|
<?program sntp>
|
|
@end example
|
|
@noindent
|
|
Do not mix these styles within one configuration file.
|
|
|
|
Compound values and carefully constructed string values may also be
|
|
specified using XML syntax:
|
|
@example
|
|
<option-name>
|
|
<sub-opt>...<...>...</sub-opt>
|
|
</option-name>
|
|
@end example
|
|
@noindent
|
|
yielding an @code{option-name.sub-opt} string value of
|
|
@example
|
|
"...<...>..."
|
|
@end example
|
|
@code{AutoOpts} does not track suboptions. You simply note that it is a
|
|
hierarchicly valued option. @code{AutoOpts} does provide a means for searching
|
|
the associated name/value pair list (see: optionFindValue).
|
|
|
|
The command line options relating to configuration and/or usage help are:
|
|
|
|
@subsubheading version (-)
|
|
|
|
Print the program version to standard out, optionally with licensing
|
|
information, then exit 0. The optional argument specifies how much licensing
|
|
detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
|
|
Only the first letter of the argument is examined:
|
|
|
|
@table @samp
|
|
@item version
|
|
Only print the version. This is the default.
|
|
@item copyright
|
|
Name the copyright usage licensing terms.
|
|
@item verbose
|
|
Print the full copyright usage licensing terms.
|
|
@end table
|
|
|
|
@node sntp exit status
|
|
@subsection sntp exit status
|
|
|
|
One of the following exit values will be returned:
|
|
@table @samp
|
|
@item 0 (EXIT_SUCCESS)
|
|
Successful program execution.
|
|
@item 1 (EXIT_FAILURE)
|
|
The operation failed or the command syntax was not valid.
|
|
@item 66 (EX_NOINPUT)
|
|
A specified configuration file could not be loaded.
|
|
@item 70 (EX_SOFTWARE)
|
|
libopts had an internal operational error. Please report
|
|
it to autogen-users@@lists.sourceforge.net. Thank you.
|
|
@end table
|
|
@node sntp Usage
|
|
@subsection sntp Usage
|
|
@node sntp Authors
|
|
@subsection sntp Authors
|