346 lines
9.5 KiB
Plaintext
346 lines
9.5 KiB
Plaintext
/* -*- Mode: Text -*- */
|
|
|
|
autogen definitions options;
|
|
|
|
#include copyright.def
|
|
#include homerc.def
|
|
#include autogen-version.def
|
|
|
|
prog-name = "ntpq";
|
|
prog-title = "standard NTP query program";
|
|
argument = '[ host ...]';
|
|
|
|
test-main;
|
|
|
|
flag = {
|
|
name = ipv4;
|
|
value = 4;
|
|
equivalence = ipv4;
|
|
descrip = "Force IPv4 DNS name resolution";
|
|
doc = <<- _EndOfDoc_
|
|
Force DNS resolution of following host names on the command line
|
|
to the IPv4 namespace.
|
|
_EndOfDoc_;
|
|
};
|
|
|
|
flag = {
|
|
name = ipv6;
|
|
value = 6;
|
|
equivalence = ipv4;
|
|
descrip = "Force IPv6 DNS name resolution";
|
|
doc = <<- _EndOfDoc_
|
|
Force DNS resolution of following host names on the command line
|
|
to the IPv6 namespace.
|
|
_EndOfDoc_;
|
|
};
|
|
|
|
flag = {
|
|
name = command;
|
|
value = c;
|
|
arg-type = string;
|
|
descrip = "run a command and exit";
|
|
max = NOLIMIT;
|
|
arg-name = cmd;
|
|
stack-arg;
|
|
doc = <<- _EndOfDoc_
|
|
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).
|
|
_EndOfDoc_;
|
|
};
|
|
|
|
#include debug-opt.def
|
|
|
|
flag = {
|
|
name = peers;
|
|
value = p;
|
|
descrip = "Print a list of the peers";
|
|
flags-cant = interactive;
|
|
doc = <<- _EndOfDoc_
|
|
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.
|
|
_EndOfDoc_;
|
|
};
|
|
|
|
flag = {
|
|
name = interactive;
|
|
value = i;
|
|
flags-cant = command, peers;
|
|
descrip = "Force ntpq to operate in interactive mode";
|
|
doc = <<- _EndOfDoc_
|
|
Force ntpq to operate in interactive mode. Prompts will be written
|
|
to the standard output and commands read from the standard input.
|
|
_EndOfDoc_;
|
|
};
|
|
|
|
flag = {
|
|
name = numeric;
|
|
value = n;
|
|
descrip = "numeric host addresses";
|
|
doc = <<- _EndOfDoc_
|
|
Output all host addresses in dotted-quad numeric format rather than
|
|
converting to the canonical host names.
|
|
_EndOfDoc_;
|
|
};
|
|
|
|
detail = <<- _END_DETAIL
|
|
The
|
|
[= prog-name =]
|
|
utility program is used to query NTP servers which
|
|
implement the standard NTP mode 6 control message formats defined
|
|
in Appendix B of the NTPv3 specification RFC1305, requesting
|
|
information about current state and/or changes in that state.
|
|
The same formats are used in NTPv4, although some of the
|
|
variables have changed and new ones added.
|
|
_END_DETAIL;
|
|
|
|
prog-man-descrip = <<- _END_PROG_MAN_DESCRIP
|
|
The
|
|
[= prog-name =]
|
|
utility program is used to query NTP servers which
|
|
implement the standard NTP mode 6 control message formats defined
|
|
in Appendix B of the NTPv3 specification RFC1305, requesting
|
|
information about current state and/or changes in that state.
|
|
The same formats are used in NTPv4, although some of the
|
|
variables have changed and new ones added. The description on this
|
|
page is for the NTPv4 variables.
|
|
The program may be run either in interactive mode or controlled using
|
|
command line arguments.
|
|
Requests to read and write arbitrary
|
|
variables can be assembled, with raw and pretty-printed output
|
|
options being available.
|
|
The
|
|
[= prog-name =]
|
|
utility can also obtain and print a
|
|
list of peers in a common format by sending multiple queries to the
|
|
server.
|
|
|
|
If one or more request options is included on the command line
|
|
when
|
|
[= prog-name =]
|
|
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,
|
|
[= prog-name =]
|
|
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
|
|
[= prog-name =]
|
|
utility will prompt for
|
|
commands if the standard input is a terminal device.
|
|
|
|
The
|
|
[= prog-name =]
|
|
utility uses NTP mode 6 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
|
|
[= prog-name =]
|
|
utility makes
|
|
one attempt to retransmit requests, and will time requests out if
|
|
the remote host is not heard from within a suitable timeout
|
|
time.
|
|
|
|
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,
|
|
[= prog-name =]
|
|
will attempt to read
|
|
interactive format commands from the standard input.
|
|
.Ss "Internal 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.
|
|
|
|
A
|
|
number of interactive format commands are executed entirely within
|
|
the
|
|
[= prog-name =]
|
|
utility itself and do not result in NTP mode 6
|
|
requests being sent to a server.
|
|
These are described following.
|
|
@table @code
|
|
@item ? [command_keyword]
|
|
@itemx help [command_keyword]
|
|
A
|
|
.Ql \&?
|
|
by itself will print a list of all the command
|
|
keywords known to this incarnation of
|
|
[= prog-name =] .
|
|
A
|
|
.Ql \&?
|
|
followed by a command keyword will print function and usage
|
|
information about the command.
|
|
This command is probably a better
|
|
source of information about
|
|
[= prog-name =]
|
|
than this manual
|
|
page.
|
|
@item addvars
|
|
.Ar variable_name [=value] ...
|
|
.Xc
|
|
@item rmvars variable_name ...
|
|
@item clearvars
|
|
The data carried by NTP mode 6 messages consists of a list of
|
|
items of the form
|
|
.Ql variable_name=value ,
|
|
where the
|
|
.Ql =value
|
|
is ignored, and can be omitted,
|
|
in requests to the server to read variables.
|
|
The
|
|
[= prog-name =]
|
|
utility maintains an internal list in which data to be included in control
|
|
messages can be assembled, and sent using the
|
|
.Ic readlist
|
|
and
|
|
.Ic writelist
|
|
commands described below.
|
|
The
|
|
.Ic addvars
|
|
command allows variables and their optional values to be added to
|
|
the list.
|
|
If more than one variable is to be added, the list should
|
|
be comma-separated and not contain white space.
|
|
The
|
|
.Ic rmvars
|
|
command can be used to remove individual variables from the list,
|
|
while the
|
|
.Ic clearlist
|
|
command removes all variables from the
|
|
list.
|
|
@item authenticate [ yes | no ]
|
|
Normally
|
|
[= prog-name =]
|
|
does not authenticate requests unless
|
|
they are write requests.
|
|
The command
|
|
.Ql authenticate yes
|
|
causes
|
|
[= prog-name =]
|
|
to send authentication with all requests it
|
|
makes.
|
|
Authenticated requests causes some servers to handle
|
|
requests slightly differently, and can occasionally melt the CPU in
|
|
fuzzballs if you turn authentication on before doing a
|
|
.Ic peer
|
|
display.
|
|
The command
|
|
.Ql authenticate
|
|
causes
|
|
[= prog-name =]
|
|
to display whether or not
|
|
[= prog-name =]
|
|
is currently autheinticating requests.
|
|
@item cooked
|
|
Causes output from query commands to be "cooked", so that
|
|
variables which are recognized by
|
|
[= prog-name =]
|
|
will have their
|
|
values reformatted for human consumption.
|
|
Variables which
|
|
[= prog-name =]
|
|
thinks should have a decodable value but didn't are
|
|
marked with a trailing
|
|
.Ql \&? .
|
|
.@item debug [
|
|
.Cm more |
|
|
.Cm less |
|
|
.Cm off
|
|
]
|
|
.Xc
|
|
With no argument, displays the current debug level.
|
|
Otherwise, the debug level is changed to the indicated level.
|
|
@item delay 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.
|
|
@item host hostname
|
|
Set the host to which future queries will be sent.
|
|
Hostname may
|
|
be either a host name or a numeric address.
|
|
@item hostnames 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.
|
|
@item keyid 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.
|
|
@item ntpversion [
|
|
.Cm 1 |
|
|
.Cm 2 |
|
|
.Cm 3 |
|
|
.Cm 4
|
|
]
|
|
.Xc
|
|
Sets the NTP version number which
|
|
[= prog-name =]
|
|
claims in
|
|
packets.
|
|
Defaults to 3, Note that mode 6 control messages (and
|
|
modes, for that matter) didn't exist in NTP version 1.
|
|
There appear
|
|
to be no servers left which demand version 1.
|
|
With no argument, displays the current NTP version that will be used
|
|
when communicating with servers.
|
|
@item quit
|
|
Exit
|
|
[= prog-name =] .
|
|
@item 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.
|
|
@item raw
|
|
Causes all output from query commands is printed as received
|
|
from the remote server.
|
|
The only formating/interpretation done on
|
|
the data is to transform nonascii data into a printable (but barely
|
|
understandable) form.
|
|
@item timeout Ar milliseconds
|
|
Specify a timeout period for responses to server queries.
|
|
The
|
|
default is about 5000 milliseconds.
|
|
Note that since
|
|
[= prog-name =]
|
|
retries each query once after a timeout, the total waiting time for
|
|
a timeout will be twice the timeout value set.
|
|
@end table
|
|
|
|
_END_PROG_MAN_DESCRIP;
|