The ntpq utility program is used to monitor the operational status and determine the performance of ntpd, the NTP daemon.
ntpq
ntpd
This document applies to version 4.2.8p12 of ntpq.
The ntpq utility program is used to monitor NTP daemon ntpd operations and determine performance. It uses the standard NTP mode 6 control message formats defined in Appendix B of the NTPv3 specification RFC1305. The same formats are used in NTPv4, although some of the variable names have changed and new ones added. The description on this page is for the NTPv4 variables.
The program can 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 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. ntpq 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. ntpq makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time.
Note that in contexts where a host name is expected, a -4 qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a -6 qualifier forces DNS resolution to the IPv6 namespace.
-4
-6
For examples and usage, see the NTP Debugging Techniques page.
The ntpq utility program is used to query NTP servers to monitor NTP operations and performance, requesting information about current state and/or changes in that state. 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.
Note that in contexts where a host name is expected, a -4 qualifier preceding the host name forces resolution to the IPv4 namespace, while a -6 qualifier forces resolution to the IPv6 namespace. For examples and usage, see the NTP Debugging Techniques page.
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.
-i
-n
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 requests being sent to a server. These are described following.
?
[
]
help
addvars
[=
[,...]
rmvars
clearvars
showvars
readlist
writelist
authenticate
[yes|no]
yes
cooked
debug
[more|less|off]
delay
drefid
[hash|ipv4]
exit
host
hostnames
no
keyid
controlkey
keytype
MD5
ntpversion
[1|2|3|4]
passwd
poll
[verbose]
quit
raw
timeout
version
Association ids are used to identify system, peer and clock variables. System variables are assigned an association id of zero and system name space, while each association is assigned a nonzero association id and peer namespace. Most control commands send a single message to the server and expect a single response message. The exceptions are the peers command, which sends a series of messages, and the mreadlist and mreadvar commands, which iterate over a range of associations.
peers
mreadlist
mreadvar
apeers
[tally]remote refid assid st t when pool reach delay offset jitter
where the output is just like the peers command except that the refid is displayed in hex format and the association number is also displayed.
refid
associations
ind assid status conf reach auth condition last_event cnt
ind
Ta
index
on
this
list
assid
association
id
status
peer
word
conf
No
persistent,
ephemeral
reach
reachable,
unreachable
auth
ok
bad
and
none
condition
selection
(see
the
select
field
of
word)
last_event
event
report
cnt
count
authinfo
clocklist
cl
clockvar
]]
cv
:config
config-from-file
ifstats
iostats
kerninfo
lassociations
lopeers
[-4|-6]
dstadr
lpassociations
lpeers
monstats
mrl
mrv
readvar
mrulist
[limited | kod | mincount=
| laddr=
| sort=[-]
| resany=
| resall=
sort
[-]
ntpd(8)
limited
kod
mincount
laddr
resany
resall
0x
lstint
addr
avgint
rstr
restrict
r
L
K
m
v
rport
remote
address
opeers
[-4 | -6]
passociations
[tally]remote refid st t when pool reach delay offset jitter
[tally]
-w
st
t
u
b
p
l
s
A
B
M
when
offset
jitter
pstats
rl
] [, ...]]
rv
reslist
saveconfig
date(1)
saveconfig ntp-%Y%m%d-%H%M%S.conf.
The filename used is stored in system variable savedconfig. Authentication is required.
savedconfig
sysinfo
sysstats
timerstats
writevar
[, ...]
The current state of the operating program is shown in a set of status words maintained by the system. Status information is also available on a per-association basis. These words are displayed by the readlist and associations commands both in hexadecimal and in decoded short tip strings. The codes, tips and short explanations are documented on the .Lk decode.html "Event Messages and Status Words" page. The page also includes a list of system and peer messages, the code for the latest of which is included in the status word.
Information resulting from protocol machine state transitions is displayed using an informal set of ASCII strings called .Lk decode.html#kiss "kiss codes" . The original purpose was for kiss-o'-death (KoD) packets sent by the server to advise the client of an unusual condition. They are now displayed, when appropriate, in the reference identifier field in various billboards.
The following system variables appear in the readlist billboard. Not all variables are displayed in some configurations.
processor
system
leap
stratum
precision
rootdelay
rootdisp
reftime
clock
tc
mintc
frequency
sys_jitter
clk_wander
clk_jitter
tai
leapsec
expire
When the NTPv4 daemon is compiled with the OpenSSL software library, additional system variables are displayed, including some or all of the following, depending on the particular Autokey dance:
ident
flags
digest
signature
update
cert
until
The following peer variables appear in the readlist billboard for each association. Not all variables are displayed in some configurations.
associd
srcadr
srcport
dstport
rec
unreach
hmode
pmode
hpoll
ppoll
headway
flash
dispersion
bias
xleave
When the NTPv4 daemon is compiled with the OpenSSL software library, additional peer variables are displayed, including the following:
initsequence
initkey
timestamp
The following clock variables appear in the clocklist billboard for each association with a reference clock. Not all variables are displayed in some configurations.
device
timecode
noreply
badformat
baddata
fudgetime1
fudgetime2
This section was generated by AutoGen, using the agtexi-cmd template and the option descriptions for the ntpq program. This software is released under the NTP license, <http://ntp.org/license>.
agtexi-cmd
This is the automatically generated usage text for ntpq.
The text printed is the same whether selected with the help option (--help) or the more-help option (--more-help). more-help will print the usage text by passing it through a pager program. more-help is disabled on platforms without a working fork(2) function. The PAGER environment variable is used to select the program, defaulting to more. Both will exit with a status code of 0.
more-help
fork(2)
PAGER
ntpq - standard NTP query program - Ver. 4.2.8p11 Usage: ntpq [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ host ...] Flg Arg Option-Name Description -4 no ipv4 Force IPv4 name resolution - prohibits the option 'ipv6' -6 no ipv6 Force IPv6 name resolution - prohibits the option 'ipv4' -c Str command run a command and exit - 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 -i no interactive Force ntpq to operate in interactive mode - prohibits these options: command peers -n no numeric numeric host addresses no old-rv Always output status line with readvar -p no peers Print a list of the peers - prohibits the option 'interactive' -r KWd refid Set default display type for S2+ refids -w no wide Display the full 'remote' value 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 NTPQ_* The valid "refid" option keywords are: hash ipv4 or an integer from 0 through 1 Please send bug reports to: <http://bugs.ntp.org, bugs@ntp.org>
This is the “force ipv4 name resolution” option.
This option has some usage constraints. It:
Force resolution of following host names on the command line to the IPv4 namespace.
This is the “force ipv6 name resolution” option.
Force resolution of following host names on the command line to the IPv6 namespace.
This is the “run a command and exit” option. This option takes a string argument cmd.
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).
This is the “force ntpq to operate in interactive mode” option.
Force ntpq to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.
This is the “numeric host addresses” option. Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
This is the “always output status line with readvar” option. 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.
associd=...
ntpq -c "rv 0 offset"
This is the “print a list of the peers” option.
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.
This is the “set default display type for s2+ refids” option. This option takes a keyword argument.
hash ipv4
or their numeric equivalent.
Set the default display format for S2+ refids.
This is the “display the full 'remote' value” option. Display the full value of the 'remote' value. If this requires more than 15 characters, display the full value, emit a newline, and continue the data display properly indented on the next line.
Any option that is not marked as not presettable may be preset by loading values from configuration ("rc" or "ini") files, and values from environment variables named NTPQ and NTPQ_<OPTION_NAME>. <OPTION_NAME> must be one of the options listed above in upper case and segmented with underscores. The NTPQ 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.
NTPQ
NTPQ_<OPTION_NAME>
<OPTION_NAME>
libopts will search in 2 places for configuration files:
libopts
HOME
PWD
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:
[NTPQ]
or by
<?program ntpq>
Do not mix these styles within one configuration file.
Compound values and carefully constructed string values may also be specified using XML syntax:
<option-name> <sub-opt>...<...>...</sub-opt> </option-name>
yielding an option-name.sub-opt string value of
option-name.sub-opt
"...<...>..."
AutoOpts does not track suboptions. You simply note that it is a hierarchicly valued option. AutoOpts does provide a means for searching the associated name/value pair list (see: optionFindValue).
AutoOpts
The command line options relating to configuration and/or usage help are:
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:
One of the following exit values will be returned:
/etc/ntp.conf
-c
conffile
-f
driftfile
leapfile
-p
pidfile
-l
logfile
includefile
/var/NTP
-s
statsdir
/usr/local/etc
-k
keysdir
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 >, followed by a file name, to the command line. A number of interactive format commands are executed entirely within the ntpq program itself and do not result in NTP mode-6 requests being sent to a server. These are described following.
>
? [
help [
>addvars
[ =
] [...]
[...]
clearvars</dt>
=
clearlist
debug more | less | off
hostnames [yes | no]
ntp.conf
AES128CMAC
MD2
MD4
MDC2
RIPEMD160
SHA
SHA1
ntpversion 1 | 2 | 3 | 4
Association IDs are used to identify system, peer and clock variables. System variables are assigned an association ID of zero and system name space, while each association is assigned a nonzero association ID and peer namespace. Most control commands send a single mode-6 message to the server and expect a single response message. The exceptions are the peers command, which sends a series of messages, and the mreadlist and mreadvar commands, which iterate over a range of associations.
[...]] [...]]
[...] ][...]]
:config [...]
mrulist [limited | kod | mincount=
| sort=
sort=
mincount=
laddr=
resany=
resall=
remote address
[ ... ]
associations command
] [,...]
strftime()
saveconfig ntp-%Y%m%d-%H%M%S.conf
The current state of the operating program is shown in a set of status words maintained by the system and each association separately. These words are displayed in the rv and as commands both in hexadecimal and decoded short tip strings. The codes, tips and short explanations are on the Event Messages and Status Words page. The page also includes a list of system and peer messages, the code for the latest of which is included in the status word.
as
Information resulting from protocol machine state transitions is displayed using an informal set of ASCII strings called kiss codes. The original purpose was for kiss-o'-death (KoD) packets sent by the server to advise the client of an unusual condition. They are now displayed, when appropriate, in the reference identifier field in various billboards.
The following system variables appear in the rv billboard. Not all variables are displayed in some configurations.
The jitter and wander statistics are exponentially-weighted RMS averages. The system jitter is defined in the NTPv4 specification; the clock jitter statistic is computed by the clock discipline module.
The following peer variables appear in the rv billboard for each association. Not all variables are displayed in some configurations.
The bias variable is calculated when the first broadcast packet is received after the calibration volley. It represents the offset of the broadcast subgraph relative to the unicast subgraph. The xleave variable appears only the interleaved symmetric and interleaved modes. It represents the internal queuing, buffering and transmission delays for the preceding packet.
The following clock variables appear in the cv billboard for each association with a reference clock. Not all variables are displayed in some configurations.