1 \input texinfo @c -*-texinfo-*-
4 @settitle ntpq: Network Time Protocol Query User's Manual
5 @include ../sntp/include/version.texi
10 This file documents the use of the NTP Project's ntpq, a program for
11 querying the state of an NTP server.
15 * ntpq: (ntpq). NTP Query program
19 @title ntpq: Network Time Protocol Query User's Manual
20 @subtitle ntpq, version @value{VERSION}, @value{UPDATED}
21 @c @author Max @email{foo@ntp.org}
25 @c @vskip 0pt plus 1filll
29 @node Top, ntpq Description, (dir), (dir)
30 @top ntpq: Network Time Protocol Query User Manual
32 The @code{ntpq} utility program is used to
33 monitor the operational status
34 and determine the performance of
35 @code{ntpd}, the NTP daemon.
37 This document applies to version @value{VERSION} of @code{ntpq}.
41 * ntpq Invocation:: Invoking ntpq
44 * Control Message Commands::
45 * Status Words and Kiss Codes::
51 @node ntpq Description, Usage, Top, Top
52 @comment node-name, next, previous, up
55 The @code{ntpq} utility program is used to monitor NTP daemon @code{ntpd} operations and determine performance.
56 It uses the standard NTP mode 6 control message formats defined in
57 Appendix B of the NTPv3 specification RFC1305.
58 The same formats are used in NTPv4, although some of the variable names have changed and new ones added.
59 The description on this page is for the NTPv4 variables.
61 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.
63 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.
65 @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.
67 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.
69 For examples and usage, see the @url{debug.html, NTP Debugging Techniques} page.
71 @include invoke-ntpq.texi
73 @node Usage, Internal Commands, ntpq Description, Top
74 @comment node-name, next, previous, up
77 @multitable @columnfractions .23 .23 .05 .15
78 @headitem What @tab Default @tab Flag @tab Option
79 @item configuration file
80 @tab @code{/etc/ntp.conf}
87 @item leapseconds file
102 @tab @code{includefile}
103 @item statistics path
108 @tab @code{/usr/local/etc}
113 @node Internal Commands, Control Message Commands, Usage, Top
114 @comment node-name, next, previous, up
115 @section Internal Commands
117 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.
121 @item @anchor{help} @code{? [}@kbd{command_keyword}@code{]}
122 @itemx @code{help [}@kbd{command_keyword}@code{]}
123 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.
125 @item @anchor{addvars} >@code{addvars @kbd{name} [ = @kbd{value}] [...]}
126 @itemx @code{rmvars @kbd{name} [...]}
127 @itemx @code{clearvars}</dt>
128 The arguments to these commands consist of a list of items of the form
129 @code{@kbd{name} = @kbd{value}}, where the @code{= @kbd{value}} is ignored,
130 and can be omitted in read requests.
131 @code{ntpq} maintains an internal list in which data to be included
132 in control messages can be assembled, and sent using the @code{readlist}
133 and @code{writelist} commands described below.
134 The @code{addvars} command allows variables and optional values
135 to be added to the list.
136 If more than one variable is to be added
137 the list should be comma-separated and not contain white space.
138 The @code{rmvars} command can be used to remove individual variables
140 while the @code{clearlist} command removes all variables from the list.
142 @item @anchor{cooked} @code{cooked}
143 Display server messages in prettyprint format.
145 @item @anchor{debug} @code{debug more | less | off}
146 Turns internal query program debugging on and off.
148 @item @anchor{delay} @code{delay @kbd{milliseconds}}
149 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.
151 @item @anchor{host} @code{host @kbd{name}}
152 Set the host to which future queries will be sent.
153 The name may be either a DNS name or a numeric address.
155 @item @anchor{hostnames} @code{hostnames [yes | no]}
156 If @code{yes} is specified, host names are printed in information displays.
157 If @code{no} is specified, numeric addresses are printed instead.
158 The default is @code{yes},
159 unless modified using the command line @code{-n} switch.
161 @item @anchor{keyid} @code{keyid @kbd{keyid}}
162 This command specifies the key number to be used
163 to authenticate configuration requests.
164 This must correspond to a key ID configured in @code{ntp.conf} for this purpose.
166 @item @anchor{keytype} @code{keytype}
167 Specify the digest algorithm to use for authenticated requests,
168 with default @code{MD5}.
169 If the OpenSSL library is installed,
170 digest can be be any message digest algorithm supported by the library.
171 The current selections are: @code{MD2}, @code{MD4}, @code{MD5}, @code{MDC2}, @code{RIPEMD160}, @code{SHA} and @code{SHA1}.
173 @item @anchor{ntpversion} @code{ntpversion 1 | 2 | 3 | 4}
174 Sets the NTP version number which @code{ntpq} claims in packets.
176 Note that mode-6 control messages (and modes, for that matter)
177 didn't exist in NTP version 1.
179 @item @anchor{passwd} @code{passwd}
180 This command prompts for a password to authenticate requests.
181 The password must correspond to the key ID configured in @code{ntp.conf} for this purpose.
183 @item @anchor{quit} @code{quit}
186 @item @anchor{raw} @code{raw}
187 Display server messages as received and without reformatting.
189 @item @anchor{timeout} @code{timeout @kbd{millseconds}}
190 Specify a timeout period for responses to server queries.
191 The default is about 5000 milliseconds.
192 Note that since @code{ntpq} retries each query once after a timeout
193 the total waiting time for a timeout will be twice the timeout value set.
197 @node Control Message Commands, Status Words and Kiss Codes, Internal Commands, Top
198 @comment node-name, next, previous, up
199 @section Control Message Commands
201 Association IDs are used to identify system, peer and clock variables.
202 System variables are assigned an association ID of zero and system name space,
203 while each association is assigned a nonzero association ID and peer namespace.
204 Most control commands send a single mode-6 message to the server
205 and expect a single response message.
206 The exceptions are the @code{peers} command,
207 which sends a series of messages,
208 and the @code{mreadlist} and @code{mreadvar} commands,
209 which iterate over a range of associations.
213 @item @code{associations}
214 Display a list of mobilized associations in the form:
216 @code{ind assid status conf reach auth condition last_event cnt}
218 @multitable @columnfractions .1 .4
219 @headitem Variable @tab Description
222 @tab index on this list
228 @tab @url{decode.html#peer, peer status word}
231 @tab @code{yes}: persistent, @code{no}: ephemeral
234 @tab @code{yes}: reachable, @code{no}: unreachable
237 @tab @code{ok}, @code{yes}, @code{bad} and @code{none}
239 @item @code{condition}
240 @tab selection status (see the @code{select} field of the @url{decode.html#peer, peer status word})
242 @item @code{last_event}
243 @tab event report (see the @code{event} field of the @url{decode.html#peer, peer status word})
246 event count (see the @code{count} field of the @url{decode.html#peer, peer status word})
250 @item @anchor{cv} clockvar @kbd{assocID} [@kbd{name} [ = @kbd{value} [...]] [...]]
251 @itemx cv @kbd{assocID} [@kbd{name} [ = @kbd{value} [...] ][...]]
252 Display a list of @ref{clock,,clock variables} for those associations supporting a reference clock.
254 @item @anchor{:config} :config [...]
255 Send the remainder of the command line, including whitespace, to the server
256 as a run-time configuration command in the same format
257 as the configuration file.
258 This command is experimental until further notice and clarification.
259 Authentication is of course required.
261 @item @anchor{config-from-file} config-from-file @kbd{filename}
262 Send the each line of @kbd{filename} to the server as
263 run-time configuration commands in the same format as the configuration file.
264 This command is experimental until further notice and clarification.
265 Authentication is required.
267 @item @anchor{ifstats} ifstats
268 Display statistics for each local network address.
269 Authentication is required.
271 @item @anchor{iostats} iostats
272 Display network and reference clock I/O statistics.
274 @item @anchor{kerninfo} kerninfo
275 Display kernel loop and PPS statistics.
276 As with other ntpq output, times are in milliseconds.
277 The precision value displayed is in milliseconds as well,
278 unlike the precision system variable.
280 @item @anchor{lassoc} lassociations
281 Perform the same function as the associations command,
282 except display mobilized and unmobilized associations.
284 @item @anchor{monstats} monstats
285 Display monitor facility statistics.
287 @item @anchor{mrulist} mrulist [limited | kod | mincount=@kbd{count} | laddr=@kbd{localaddr} | sort=@kbd{sortorder} | resany=@kbd{hexmask} | resall=@kbd{hexmask}]
288 Obtain and print traffic counts collected and maintained by
289 the monitor facility.
290 With the exception of @code{sort=@kbd{sortorder}},
291 the options filter the list returned by @code{ntpd}.
292 The @code{limited} and @code{kod} options return only entries
293 representing client addresses from which the last packet received
294 triggered either discarding or a KoD response.
295 The @code{mincount=@kbd{count}} option filters entries representing
296 less than @code{@kbd{count}} packets.
297 The @code{laddr=@kbd{localaddr}} option filters entries for packets
298 received on any local address other than @code{@kbd{localaddr}}.
299 @code{resany=@kbd{hexmask}} and @code{resall=@kbd{hexmask}}
300 filter entries containing none or less than all, respectively,
301 of the bits in @code{@kbd{hexmask}}, which must begin with @code{0x}.
303 The @code{@kbd{sortorder}} defaults to @code{lstint} and may be any of
304 @code{addr}, @code{count}, @code{avgint}, @code{lstint}, or
305 any of those preceded by a minus sign (hyphen) to reverse the sort order.
306 The output columns are:
308 @multitable @columnfractions .1 .4
309 @headitem Column @tab Description
313 Interval in s between the receipt of the most recent packet from this
314 address and the completion of the retrieval of the MRU list by @code{ntpq}
318 Average interval in s between packets from this address.
322 Restriction flags associated with this address.
323 Most are copied unchanged from the matching @code{restrict} command,
324 however 0x400 (kod) and 0x20 (limited) flags are cleared unless
325 the last packet from this address triggered a rate control response.
329 Rate control indicator, either a period, @code{L} or @code{K} for
330 no rate control response, rate limiting by discarding, or
331 rate limiting with a KoD response, respectively.
338 Packet version number.
342 Packets received from this address.
346 Source port of last packet from this address.
348 @item @code{remote address}
350 DNS name, numeric address, or address followed by claimed DNS name which
351 could not be verified in parentheses.
355 @item @anchor{mreadvar} @code{mreadvar @kbd{assocID} @kbd{assocID} [ @kbd{variable_name} [ = @kbd{value}[ ... ]}
356 @itemx @anchor{mrv} @code{mrv @kbd{assocID} @kbd{assocID} [ @kbd{variable_name} [ = @kbd{value}[ ... ]}
357 Perform the same function as the @code{readvar} command,
358 except for a range of association IDs.
359 This range is determined from the association list cached by
360 the most recent @code{associations} command.
362 @item @anchor{passoc} @code{passociations}
363 Perform the same function as the @code{associations command}, except that
364 it uses previously stored data rather than making a new query.
366 @item @anchor{pe} @code{peers}
367 Display a list of peers in the form:
369 @code{[tally]remote refid st t when pool reach delay offset jitter}
371 @multitable @columnfractions .1 .2
372 @headitem Variable @tab Description
375 single-character code indicating current value of the @code{select} field
376 of the @url{decode.html#peer, peer status word}.
380 host name (or IP number) of peer
384 association ID or @url{decode.html#kiss, kiss code}.
392 @code{u}: unicast or manycast client,
393 @code{b}: broadcast or multicast client,
394 @code{l}: local (reference clock),
395 @code{s}: symmetric (peer),
396 @code{A}: manycast server,
397 @code{B}: broadcast server,
398 @code{M}: multicast server.
402 sec/min/hr since last received packet
406 poll interval (log(2) s)
410 reach shift register (octal)
418 offset of server relative to this host
426 @item @anchor{rv} readvar @kbd{assocID} @kbd{name} [ = @kbd{value} ] [,...]
427 @itemx rv @kbd{assocID} [ @kbd{name} ] [,...]
428 Display the specified variables.
429 If @code{@kbd{assocID}} is zero,
430 the variables are from the @ref{system, system variables} name space,
431 otherwise they are from the @ref{peer, peer variables} name space.
432 The @kbd{assocID} is required, as the same name can occur in both spaces.
433 If no @kbd{name} is included,
434 all operative variables in the name space are displayed.
435 In this case only, if the @code{@kbd{assocID}} is omitted, it is assumed zero.
436 Multiple names are specified with comma separators and without whitespace.
437 Note that time values are represented in milliseconds and
438 frequency values in parts-per-million (PPM).
439 Some NTP timestamps are represented in the format YYYYMMDDTTTT,
440 where YYYY is the year, MM the month of year, DD the day of month and
441 TTTT the time of day.
443 @item @anchor{saveconfig} @code{saveconfig @kbd{filename}}
444 Write the current configuration, including any runtime modifications
445 given with @code{:config} or @code{config-from-file},
446 to the ntpd host's file @kbd{filename}.
447 This command will be rejected by the server unless
448 @url{miscopt.html#saveconfigdir, saveconfigdir}
449 appears in the @code{ntpd} configuration file.
450 @kbd{filename} can use @code{strftime()} format specifiers
451 to substitute the current date and time, for example,
452 @code{saveconfig ntp-%Y%m%d-%H%M%S.conf}.
453 The filename used is stored in system variable @code{savedconfig}.
454 Authentication is required.
456 @item @anchor{writevar} writevar @kbd{assocID} @kbd{name} = @kbd{value} [,...]
457 Write the specified variables.
458 If the @code{@kbd{assocID}} is zero, the variables are from the
459 @ref{system, system variables} name space, otherwise they are from the
460 @ref{peer, peer variables} name space.
461 The @code{@kbd{assocID}} is required,
462 as the same name can occur in both spaces.
464 @item @anchor{sysinfo} @code{sysinfo}
465 Display operational summary.
467 @item @anchor{sysstats} @code{sysstats}
468 Print statistics counters maintained in the protocol module.
472 @node Status Words and Kiss Codes, System Variables, Control Message Commands, Top
473 @comment node-name, next, previous, up
474 @section Status Words and Kiss Codes
476 The current state of the operating program is shown
477 in a set of status words maintained by the system
478 and each association separately.
479 These words are displayed in the @code{rv} and @code{as} commands
480 both in hexadecimal and decoded short tip strings.
481 The codes, tips and short explanations are on the
482 @url{decode.html, Event Messages and Status Words} page.
483 The page also includes a list of system and peer messages,
484 the code for the latest of which is included in the status word.
486 Information resulting from protocol machine state transitions
487 is displayed using an informal set of ASCII strings called
488 @url{decode.html#kiss, kiss codes}.
489 The original purpose was for kiss-o'-death (KoD) packets sent
490 by the server to advise the client of an unusual condition.
491 They are now displayed, when appropriate,
492 in the reference identifier field in various billboards.
494 @node System Variables, Peer Variables, Status Words and Kiss Codes, Top
495 @comment node-name, next, previous, up
496 @section System Variables
498 The following system variables appear in the @code{rv} billboard.
499 Not all variables are displayed in some configurations.
501 @multitable @columnfractions .1 .2
502 @headitem Variable @tab Description
506 @url{decode.html#sys, system status word}
510 NTP software version and build time
512 @item @code{processor}
514 hardware platform and version
518 operating system and version
522 leap warning indicator (0-3)
528 @item @code{precision}
532 @item @code{rootdelay}
534 total roundtrip delay to the primary reference clock
536 @item @code{rootdisp}
538 total dispersion to the primary reference clock
542 system peer association ID
545 time constant and poll exponent (log(2) s) (3-17)
548 minimum time constant (log(2) s) (3-10)
555 reference ID or @url{decode.html#kiss, kiss code}
563 combined offset of server relative to this host
565 @item @code{sys_jitter}
567 combined system jitter
569 @item @code{frequency}
571 frequency offset (PPM) relative to hardware clock
573 @item @code{clk_wander}
575 clock frequency wander (PPM)
577 @item @code{clk_jitter}
587 NTP seconds when the next leap second is/was inserted
591 NTP seconds when the NIST leapseconds file expires
595 The jitter and wander statistics are exponentially-weighted RMS averages.
596 The system jitter is defined in the NTPv4 specification;
597 the clock jitter statistic is computed by the clock discipline module.
599 When the NTPv4 daemon is compiled with the OpenSSL software library,
600 additional system variables are displayed, including some or all of the
601 following, depending on the particular Autokey dance:
603 @multitable @columnfractions .1 .2
604 @headitem Variable @tab Description
608 Autokey host name for this host
612 Autokey group name for this host
616 host flags (see Autokey specification)
620 OpenSSL message digest algorithm
622 @item @code{signature}
624 OpenSSL digest/signature scheme
628 NTP seconds at last signature update
632 certificate subject, issuer and certificate flags
636 NTP seconds when the certificate expires
640 @node Peer Variables, Clock Variables, System Variables, Top
641 @comment node-name, next, previous, up
642 @section Peer Variables
644 The following peer variables appear in the @code{rv} billboard
645 for each association.
646 Not all variables are displayed in some configurations.
648 @multitable @columnfractions .1 .2
649 @headitem Variable @tab Description
657 @url{decode.html#peer, peer status word}
660 @itemx @code{srcport}
662 source (remote) IP address and port
665 @itemx @code{dstport}
667 destination (local) IP address and port
677 @item @code{precision}
681 @item @code{rootdelay}
683 total roundtrip delay to the primary reference clock
685 @item @code{rootdisp}
686 @tab total root dispersion to the primary reference clock
690 reference ID or @url{decode.html#kiss, kiss code}
698 reach register (octal)
714 host poll exponent (log(2) s) (3-17)
717 peer poll exponent (log(2) s) (3-17)
721 headway (see @url{rate.html, Rate Management and the Kiss-o'-Death Packet})
725 @url{decode.html#flash, flash status word}
735 @item @code{dispersion}
745 Autokey group name for this association
749 unicast/broadcast bias
753 interleave delay (see @url{xleave.html, NTP Interleaved Modes})
757 The bias variable is calculated when the first broadcast packet is received
758 after the calibration volley. It represents the offset of the broadcast
759 subgraph relative to the unicast subgraph. The xleave variable appears
760 only the interleaved symmetric and interleaved modes. It represents
761 the internal queuing, buffering and transmission delays for the preceding
764 When the NTPv4 daemon is compiled with the OpenSSL software library,
765 additional peer variables are displayed, including the following:
767 @multitable @columnfractions .1 .2
768 @headitem Variable @tab Description
772 peer flags (see Autokey specification)
780 peer flags (see Autokey specification)
782 @item @code{signature}
784 OpenSSL digest/signature scheme
786 @item @code{initsequence}
794 @item @code{timestamp}
796 Autokey signature timestamp
800 @node Clock Variables, , Peer Variables, Top
801 @comment node-name, next, previous, up
802 @section Clock Variables
804 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.
806 @multitable @columnfractions .1 .2
807 @headitem Variable @tab Description
811 @tab @url{decode.html#clock, clock status word}
813 @tab device description
814 @item @code{timecode}
815 @tab ASCII time code string (specific to device)
817 @tab poll messages sent
820 @item @code{badformat}
823 @tab bad date or time
824 @item @code{fudgetime1}
826 @item @code{fudgetime2}
831 @tab driver reference ID