NAME
ntpq —
standard NTP query
program
SYNOPSIS
ntpq |
[-flags]
[-flag
[value]]
[--option-name[[=|
]value]] [ host ...] |
DESCRIPTION
The
ntpq 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
ntpq
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
ntpq 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,
ntpq 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
ntpq utility will prompt for commands
if the standard input is a terminal device.
ntpq 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
ntpq 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
-i
or
-n will cause the specified query (queries) to be sent to
the indicated host(s) immediately. Otherwise,
ntpq will
attempt to read interactive format commands from the standard input.
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
ntpq utility itself and do not result in
NTP mode 6 requests being sent to a server. These are described following.
- ?
[command_keyword]
-
- help
[command_keyword]
- A ‘
?
’ by itself will
print a list of all the command keywords known to this incarnation of
ntpq. A ‘?
’ followed
by a command keyword will print function and usage information about the
command. This command is probably a better source of information about
ntpq than this manual page.
- addvars
variable_name
[=value]
...
-
- rmvars
variable_name ...
-
- clearvars
- The data carried by NTP mode 6 messages consists of a list
of items of the form
‘
variable_name=value
’, where the
‘=value
’ is ignored, and can be
omitted, in requests to the server to read variables. The
ntpq utility maintains an internal list in which data to
be included in control messages can be assembled, and sent using the
readlist and writelist commands
described below. The 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 rmvars command can be used to
remove individual variables from the list, while the
clearlist command removes all variables from the
list.
- authenticate
[yes | no]
- Normally ntpq does not authenticate
requests unless they are write requests. The command
‘
authenticate yes
’ causes
ntpq 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 peer display. The
command ‘authenticate
’ causes
ntpq to display whether or not ntpq is
currently autheinticating requests.
- cooked
- Causes output from query commands to be "cooked",
so that variables which are recognized by ntpq will have
their values reformatted for human consumption. Variables which
ntpq thinks should have a decodable value but didn't are
marked with a trailing ‘
?
’.
- debug
[more | less |
off]
- With no argument, displays the current debug level.
Otherwise, the debug level is changed to the indicated level.
- 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.
- host
hostname
- Set the host to which future queries will be sent.
hostname may be either a host name or a numeric
address.
- hostnames
[yes | no]
- If yes is specified, host names are
printed in information displays. If no is specified,
numeric addresses are printed instead. The default is
yes, unless modified using the command line
-n switch.
- 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.
- ntpversion
[1 | 2 |
3 | 4]
- Sets the NTP version number which ntpq
claims in packets. Defaults to 3, and 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.
- quit
- Exit ntpq
- 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.
- 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.
- timeout
milliseconds
- Specify a timeout period for responses to server queries.
The default is about 5000 milliseconds. Note that since
ntpq retries each query once after a timeout, the total
waiting time for a timeout will be twice the timeout value set.
OPTIONS
-
-
- -4, --ipv4
- Force IPv4 DNS name resolution. This option must not appear
in combination with any of the following options: ipv6.
Force DNS resolution of following host names on the command line to the IPv4
namespace.
-
-
- -6, --ipv6
- Force IPv6 DNS name resolution. This option must not appear
in combination with any of the following options: ipv4.
Force DNS resolution of following host names on the command line to the IPv6
namespace.
-
-
- -c cmd,
--command=cmd
- run a command and exit. This option may appear an unlimited
number of times.
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).
-
-
- -d, --debug-level
- Increase debug verbosity level. This option may appear an
unlimited number of times.
-
-
- -D number,
--set-debug-level=number
- Set the debug verbosity level. This option may appear an
unlimited number of times. This option takes an integer number as its
argument.
-
-
- -p, --peers
- Print a list of the peers. This option must not appear in
combination with any of the following options: interactive.
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.
-
-
- -i, --interactive
- Force ntpq to operate in interactive mode. This option must
not appear in combination with any of the following options: command,
peers.
Force ntpq to operate in interactive mode. Prompts will be written to
the standard output and commands read from the standard input.
-
-
- -n, --numeric
- numeric host addresses.
Output all host addresses in dotted-quad numeric format rather than
converting to the canonical host names.
-
-
- --old-rv
- Always output status line with readvar.
By default, ntpq now suppresses the associd=... line that
precedes the output of readvar (alias rv) when a single
variable is requested, such as ntpq -c "rv 0 offset".
This option causes ntpq to include both lines of output for a
single-variable readvar. Using an environment variable to preset
this option in a script will enable both older and newer ntpq to
behave identically in this regard.
-
-
- -?, --help
- Display usage information and exit.
-
-
- -!, --more-help
- Pass the extended usage information through a pager.
-
-
- ->
[cfgfile],
--save-opts
[=cfgfile]
- Save the option state to cfgfile. The default is the
last configuration file listed in the OPTION PRESETS
section, below. The command will exit after updating the config file.
-
-
- -< cfgfile,
--load-opts=cfgfile,
--no-load-opts
- Load options from cfgfile. The no-load-opts
form will disable the loading of earlier config/rc/ini files.
--no-load-opts is handled early, out of order.
-
-
- --version
[{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.
OPTION PRESETS
Any option that is not marked as
not presettable may be preset by loading
values from configuration ("RC" or ".INI") file(s) and
values from environment variables named:
NTPQ_<option-name> or
NTPQ The environmental presets take
precedence (are processed later than) the configuration files. The
homerc files are "
$HOME", and "
.".
If any of these are directories, then the file
.ntprc is searched for
within those directories. cvt_prog='/usr/local/gnu/share/autogen/texi2mdoc'
cvt_prog=`cd `dirname "$cvt_prog"` >/dev/null && pwd
`/`basename "$cvt_prog"` cd $tmp_dir test -x "$cvt_prog" ||
die "'$cvt_prog' is not executable" {
list='synopsis description options option-presets'
for f in $list ; do cat $f ; echo ; done
rm -f $list name
list='implementation-notes environment files examples exit-status errors
compatibility see-also conforming-to history authors copyright bugs
notes'
for f in $list ; do cat $f ; echo ; done > .end-doc
rm -f $list
list=`ls -1 *`' .end-doc'
for f in $list ; do cat $f ; echo ; done
rm -f $list } 1>.doc 2>/dev/null sed -f .cmds .doc |
/usr/local/gnu/bin/grep -E -v '^[ ]*$' | $cvt_prog
ENVIRONMENT
See
OPTION PRESETS for configuration environment variables.
FILES
See
OPTION PRESETS for configuration files.
EXIT STATUS
One of the following exit values will be returned:
-
-
- 0 (EXIT_SUCCESS)
- Successful program execution.
-
-
- 1 (EXIT_FAILURE)
- The operation failed or the command syntax was not
valid.
-
-
- 66 (EX_NOINPUT)
- A specified configuration file could not be loaded.
-
-
- 70 (EX_SOFTWARE)
- libopts had an internal operational error. Please report it
to autogen-users@lists.sourceforge.net. Thank you.
AUTHORS
The University of Delaware
COPYRIGHT
Copyright (C) 1970-2013 The University of Delaware all rights reserved. This
program is released under the terms of the NTP license,
<http://ntp.org/license>.
BUGS
Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
NOTES
This manual page was
AutoGen-erated from the
ntpq option
definitions.