@settitle ntpq: Network Time Protocol Query User's Manual
@include ../sntp/include/version.texi
@paragraphindent 2
@c %**end of header
@ifinfo
This file documents the use of the NTP Project's ntpq, a program for
querying the state of an NTP server.
@end ifinfo
@direntry
* ntpq: (ntpq). NTP Query program
@end direntry
@titlepage
@title ntpq: Network Time Protocol Query User's Manual
@subtitle ntpq, version @value{VERSION}, @value{UPDATED}
@c @author Max @email{foo@ntp.org}
@end titlepage
@c @page
@c @vskip 0pt plus 1filll
@shortcontents
@node Top, ntpq Description, (dir), (dir)
@top ntpq: Network Time Protocol Query User Manual
The @code{ntpq} utility program is used to
monitor the operational status
and determine the performance of
@code{ntpd}, the NTP daemon.
This document applies to version @value{VERSION} of @code{ntpq}.
@menu
* ntpq Description::
* ntpq Invocation:: Invoking ntpq
* Usage::
* Internal Commands::
* Control Message Commands::
* Status Words and Kiss Codes::
* System Variables::
* Peer Variables::
* Clock Variables::
@end menu
@node ntpq Description, Usage, Top, Top
@comment node-name, next, previous, up
@section Description
The @code{ntpq} utility program is used to monitor NTP daemon @code{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 @code{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 @code{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, @code{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. @code{ntpq} will prompt for commands if the standard input is a terminal device.
@code{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. @code{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 @code{-4} qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a @code{-6} qualifier forces DNS resolution to the IPv6 namespace.
For examples and usage, see the @url{debug.html, NTP Debugging Techniques} page.
@include invoke-ntpq.texi
@node Usage, Internal Commands, ntpq Description, Top
@comment node-name, next, previous, up
@section Usage
@multitable @columnfractions .23 .23 .05 .15
@headitem What @tab Default @tab Flag @tab Option
@item configuration file
@tab @code{/etc/ntp.conf}
@tab @code{-c}
@tab @code{conffile}
@item frequency file
@tab none
@tab @code{-f}
@tab @code{driftfile}
@item leapseconds file
@tab none
@tab
@tab @code{leapfile}
@item process ID file
@tab none
@tab @code{-p}
@tab @code{pidfile}
@item log file
@tab system log
@tab @code{-l}
@tab @code{logfile}
@item include file
@tab none
@tab none
@tab @code{includefile}
@item statistics path
@tab @code{/var/NTP}
@tab @code{-s}
@tab @code{statsdir}
@item keys path
@tab @code{/usr/local/etc}
@tab @code{-k}
@tab @code{keysdir}
@end multitable
@node Internal Commands, Control Message Commands, Usage, Top
@comment node-name, next, previous, up
@section 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. 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 @code{>}, followed by a file name, to the command line. A number of interactive format commands are executed entirely within the @code{ntpq} program itself and do not result in NTP mode-6 requests being sent to a server. These are described following.
A @code{?} by itself will print a list of all the command keywords known to @code{ntpq}. A @code{?} followed by a command keyword will print function and usage information about the command.
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 @anchor{host} @code{host @kbd{name}}
Set the host to which future queries will be sent.
The name may be either a DNS name or a numeric address.
If the @code{@kbd{assocID}} is zero, the variables are from the
@ref{system, system variables} name space, otherwise they are from the
@ref{peer, peer variables} name space.
The @code{@kbd{assocID}} is required,
as the same name can occur in both spaces.
@item @anchor{sysinfo} @code{sysinfo}
Display operational summary.
@item @anchor{sysstats} @code{sysstats}
Print statistics counters maintained in the protocol module.
@end table
@node Status Words and Kiss Codes, System Variables, Control Message Commands, Top
@comment node-name, next, previous, up
@section Status Words and Kiss Codes
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 @code{rv} and @code{as} commands
both in hexadecimal and decoded short tip strings.
The codes, tips and short explanations are on the
@url{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
@url{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.
@node System Variables, Peer Variables, Status Words and Kiss Codes, Top
@comment node-name, next, previous, up
@section System Variables
The following system variables appear in the @code{rv} billboard.
Not all variables are displayed in some configurations.
@multitable @columnfractions .1 .2
@headitem Variable @tab Description
@item @code{status}
@tab
@url{decode.html#sys, system status word}
@item @code{version}
@tab
NTP software version and build time
@item @code{processor}
@tab
hardware platform and version
@item @code{system}
@tab
operating system and version
@item @code{leap}
@tab
leap warning indicator (0-3)
@item @code{stratum}
@tab
stratum (1-15)
@item @code{precision}
@tab
precision (log(2) s)
@item @code{rootdelay}
@tab
total roundtrip delay to the primary reference clock
@item @code{rootdisp}
@tab
total dispersion to the primary reference clock
@item @code{peer}
@tab
system peer association ID
@item @code{tc}
time constant and poll exponent (log(2) s) (3-17)
@item @code{mintc}
minimum time constant (log(2) s) (3-10)
@item @code{clock}
@tab
date and time of day
@item @code{refid}
reference ID or @url{decode.html#kiss, kiss code}
@item @code{reftime}
@tab
reference time
@item @code{offset}
@tab
combined offset of server relative to this host
@item @code{sys_jitter}
@tab
combined system jitter
@item @code{frequency}
@tab
frequency offset (PPM) relative to hardware clock
@item @code{clk_wander}
@tab
clock frequency wander (PPM)
@item @code{clk_jitter}
@tab
clock jitter
@item @code{tai}
@tab
TAI-UTC offset (s)
@item @code{leapsec}
@tab
NTP seconds when the next leap second is/was inserted
@item @code{expire}
@tab
NTP seconds when the NIST leapseconds file expires
@end multitable
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.
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:
@multitable @columnfractions .1 .2
@headitem Variable @tab Description
@item @code{host}
@tab
Autokey host name for this host
@item @code{ident}
@tab
Autokey group name for this host
@item @code{flags}
@tab
host flags (see Autokey specification)
@item @code{digest}
@tab
OpenSSL message digest algorithm
@item @code{signature}
@tab
OpenSSL digest/signature scheme
@item @code{update}
@tab
NTP seconds at last signature update
@item @code{cert}
@tab
certificate subject, issuer and certificate flags
@item @code{until}
@tab
NTP seconds when the certificate expires
@end multitable
@node Peer Variables, Clock Variables, System Variables, Top
@comment node-name, next, previous, up
@section Peer Variables
The following peer variables appear in the @code{rv} billboard
for each association.
Not all variables are displayed in some configurations.
@multitable @columnfractions .1 .2
@headitem Variable @tab Description
@item @code{associd}
@tab
association ID
@item @code{status}
@tab
@url{decode.html#peer, peer status word}
@item @code{srcadr}
@itemx @code{srcport}
@tab
source (remote) IP address and port
@item @code{dstadr}
@itemx @code{dstport}
@tab
destination (local) IP address and port
@item @code{leap}
@tab
leap indicator (0-3)
@item @code{stratum}
@tab
stratum (0-15)
@item @code{precision}
@tab
precision (log(2) s)
@item @code{rootdelay}
@tab
total roundtrip delay to the primary reference clock
@item @code{rootdisp}
@tab total root dispersion to the primary reference clock
@item @code{refid}
@tab
reference ID or @url{decode.html#kiss, kiss code}
@item @code{reftime}
@tab
reference time
@item @code{reach}
@tab
reach register (octal)
@item @code{unreach}
@tab
unreach counter
@item @code{hmode}
@tab
host mode (1-6)
@item @code{pmode}
@tab
peer mode (1-5)
@item @code{hpoll}
@tab
host poll exponent (log(2) s) (3-17)
@item @code{ppoll}
@tab
peer poll exponent (log(2) s) (3-17)
@item @code{headway}
@tab
headway (see @url{rate.html, Rate Management and the Kiss-o'-Death Packet})
@item @code{flash}
@tab
@url{decode.html#flash, flash status word}
@item @code{offset}
@tab
filter offset
@item @code{delay}
@tab
filter delay
@item @code{dispersion}
@tab
filter dispersion
@item @code{jitter}
@tab
filter jitter
@item @code{ident}
@tab
Autokey group name for this association
@item @code{bias}
@tab
unicast/broadcast bias
@item @code{xleave}
@tab
interleave delay (see @url{xleave.html, NTP Interleaved Modes})
@end multitable
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.
When the NTPv4 daemon is compiled with the OpenSSL software library,
additional peer variables are displayed, including the following:
@multitable @columnfractions .1 .2
@headitem Variable @tab Description
@item @code{flags}
@tab
peer flags (see Autokey specification)
@item @code{host}
@tab
Autokey server name
@item @code{flags}
@tab
peer flags (see Autokey specification)
@item @code{signature}
@tab
OpenSSL digest/signature scheme
@item @code{initsequence}
@tab
initial key ID
@item @code{initkey}
@tab
initial key index
@item @code{timestamp}
@tab
Autokey signature timestamp
@end multitable
@node Clock Variables, , Peer Variables, Top
@comment node-name, next, previous, up
@section Clock Variables
The following clock variables appear in the @code{cv} billboard for each association with a reference clock. Not all variables are displayed in some configurations.