xref: /freebsd/contrib/ntp/ntpq/ntpq.html (revision ef0cb5db0af0d5d5b75b74f8e534fe601b7176d7)
1<html lang="en">
2<head>
3<title>ntpq: Network Time Protocol Query User's Manual</title>
4<meta http-equiv="Content-Type" content="text/html">
5<meta name="description" content="ntpq: Network Time Protocol Query User's Manual">
6<meta name="generator" content="makeinfo 4.7">
7<link title="Top" rel="top" href="#Top">
8<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
9<meta http-equiv="Content-Style-Type" content="text/css">
10<style type="text/css"><!--
11  pre.display { font-family:inherit }
12  pre.format  { font-family:inherit }
13  pre.smalldisplay { font-family:inherit; font-size:smaller }
14  pre.smallformat  { font-family:inherit; font-size:smaller }
15  pre.smallexample { font-size:smaller }
16  pre.smalllisp    { font-size:smaller }
17  span.sc { font-variant:small-caps }
18  span.roman { font-family: serif; font-weight: normal; }
19--></style>
20</head>
21<body>
22<h1 class="settitle">ntpq: Network Time Protocol Query User's Manual</h1>
23  <div class="shortcontents">
24<h2>Short Contents</h2>
25<ul>
26<a href="#Top">ntpq: Network Time Protocol Query User Manual</a>
27</ul>
28</div>
29
30
31
32<div class="node">
33<p><hr>
34<a name="Top"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-Description">ntpq Description</a>,
35Previous:&nbsp;<a rel="previous" accesskey="p" href="#dir">(dir)</a>,
36Up:&nbsp;<a rel="up" accesskey="u" href="#dir">(dir)</a>
37<br>
38</div>
39
40<h2 class="unnumbered">ntpq: Network Time Protocol Query User Manual</h2>
41
42<p>The <code>ntpq</code> utility program is used to
43monitor the operational status
44and determine the performance of
45<code>ntpd</code>, the NTP daemon.
46
47  <p>This document applies to version 4.2.8p2 of <code>ntpq</code>.
48
49<ul class="menu">
50<li><a accesskey="1" href="#ntpq-Description">ntpq Description</a>
51<li><a accesskey="2" href="#ntpq-Invocation">ntpq Invocation</a>:              Invoking ntpq
52<li><a accesskey="3" href="#Usage">Usage</a>
53<li><a accesskey="4" href="#Internal-Commands">Internal Commands</a>
54<li><a accesskey="5" href="#Control-Message-Commands">Control Message Commands</a>
55<li><a accesskey="6" href="#Status-Words-and-Kiss-Codes">Status Words and Kiss Codes</a>
56<li><a accesskey="7" href="#System-Variables">System Variables</a>
57<li><a accesskey="8" href="#Peer-Variables">Peer Variables</a>
58<li><a accesskey="9" href="#Clock-Variables">Clock Variables</a>
59</ul>
60
61<div class="node">
62<p><hr>
63<a name="ntpq-Description"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Usage">Usage</a>,
64Previous:&nbsp;<a rel="previous" accesskey="p" href="#Top">Top</a>,
65Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
66<br>
67</div>
68
69<!-- node-name,  next,  previous,  up -->
70<h3 class="section">Description</h3>
71
72<p>The <code>ntpq</code> utility program is used to monitor NTP daemon <code>ntpd</code> operations and determine performance.
73It uses the standard NTP mode 6 control message formats defined in
74Appendix B of the NTPv3 specification RFC1305.
75The same formats are used in NTPv4, although some of the variable names have changed and new ones added.
76The description on this page is for the NTPv4 variables.
77
78  <p>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</code> can also obtain and print a list of peers in a common format by sending multiple queries to the server.
79
80  <p>If one or more request options is included on the command line when <code>ntpq</code> 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</code> 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</code> will prompt for commands if the standard input is a terminal device.
81
82  <p><code>ntpq</code> 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</code> makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time.
83
84  <p>Note that in contexts where a host name is expected, a <code>-4</code> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <code>-6</code> qualifier forces DNS resolution to the IPv6 namespace.
85
86  <p>For examples and usage, see the <a href="debug.html">NTP Debugging Techniques</a> page.
87
88<div class="node">
89<p><hr>
90<a name="ntpq-Invocation"></a>
91<br>
92</div>
93
94<h3 class="section">Invoking ntpq</h3>
95
96<p><a name="index-ntpq-1"></a><a name="index-standard-NTP-query-program-2"></a>
97
98  <p>The
99<code>ntpq</code>
100utility program is used to query NTP servers which
101implement the standard NTP mode 6 control message formats defined
102in Appendix B of the NTPv3 specification RFC1305, requesting
103information about current state and/or changes in that state.
104The same formats are used in NTPv4, although some of the
105variables have changed and new ones added. The description on this
106page is for the NTPv4 variables.
107The program may be run either in interactive mode or controlled using
108command line arguments.
109Requests to read and write arbitrary
110variables can be assembled, with raw and pretty-printed output
111options being available.
112The
113<code>ntpq</code>
114utility can also obtain and print a
115list of peers in a common format by sending multiple queries to the
116server.
117
118  <p>If one or more request options is included on the command line
119when
120<code>ntpq</code>
121is executed, each of the requests will be sent
122to the NTP servers running on each of the hosts given as command
123line arguments, or on localhost by default.
124If no request options
125are given,
126<code>ntpq</code>
127will attempt to read commands from the
128standard input and execute these on the NTP server running on the
129first host given on the command line, again defaulting to localhost
130when no other host is specified.
131The
132<code>ntpq</code>
133utility will prompt for
134commands if the standard input is a terminal device.
135
136  <p><code>ntpq</code>
137uses NTP mode 6 packets to communicate with the
138NTP server, and hence can be used to query any compatible server on
139the network which permits it.
140Note that since NTP is a UDP protocol
141this communication will be somewhat unreliable, especially over
142large distances in terms of network topology.
143The
144<code>ntpq</code>
145utility makes
146one attempt to retransmit requests, and will time requests out if
147the remote host is not heard from within a suitable timeout
148time.
149
150  <p>Specifying a
151command line option other than
152<code>-i</code>
153or
154<code>-n</code>
155will
156cause the specified query (queries) to be sent to the indicated
157host(s) immediately.
158Otherwise,
159<code>ntpq</code>
160will attempt to read
161interactive format commands from the standard input.
162
163<h5 class="subsubsection">Internal Commands</h5>
164
165<p>Interactive format commands consist of a keyword followed by zero
166to four arguments.
167Only enough characters of the full keyword to
168uniquely identify the command need be typed.
169
170  <p>A
171number of interactive format commands are executed entirely within
172the
173<code>ntpq</code>
174utility itself and do not result in NTP mode 6
175requests being sent to a server.
176These are described following.
177     <dl>
178<dt><code>?</code> <code>[</code><kbd>command_keyword</kbd><code>]</code><br><dt><code>help</code> <code>[</code><kbd>command_keyword</kbd><code>]</code><dd>A
179?
180by itself will print a list of all the command
181keywords known to this incarnation of
182<code>ntpq</code>
183A
184?
185followed by a command keyword will print function and usage
186information about the command.
187This command is probably a better
188source of information about
189<code>ntpq</code>
190than this manual
191page.
192<br><dt><code>addvars</code> <kbd>variable_name</kbd><code>[=value]</code> <code>...</code><br><dt><code>rmvars</code> <kbd>variable_name</kbd> <code>...</code><br><dt><code>clearvars</code><br><dt><code>showvars</code><dd>The data carried by NTP mode 6 messages consists of a list of
193items of the form
194variable_name=value,
195where the
196=value
197is ignored, and can be omitted,
198in requests to the server to read variables.
199The
200<code>ntpq</code>
201utility maintains an internal list in which data to be included in control
202messages can be assembled, and sent using the
203<code>readlist</code>
204and
205<code>writelist</code>
206commands described below.
207The
208<code>addvars</code>
209command allows variables and their optional values to be added to
210the list.
211If more than one variable is to be added, the list should
212be comma-separated and not contain white space.
213The
214<code>rmvars</code>
215command can be used to remove individual variables from the list,
216while the
217<code>clearlist</code>
218command removes all variables from the
219list.
220The
221<code>showvars</code>
222command displays the current list of optional variables.
223<br><dt><code>authenticate</code> <code>[yes | no]</code><dd>Normally
224<code>ntpq</code>
225does not authenticate requests unless
226they are write requests.
227The command
228authenticate yes
229causes
230<code>ntpq</code>
231to send authentication with all requests it
232makes.
233Authenticated requests causes some servers to handle
234requests slightly differently, and can occasionally melt the CPU in
235fuzzballs if you turn authentication on before doing a
236<code>peer</code>
237display.
238The command
239authenticate
240causes
241<code>ntpq</code>
242to display whether or not
243<code>ntpq</code>
244is currently autheinticating requests.
245<br><dt><code>cooked</code><dd>Causes output from query commands to be "cooked", so that
246variables which are recognized by
247<code>ntpq</code>
248will have their
249values reformatted for human consumption.
250Variables which
251<code>ntpq</code>
252thinks should have a decodable value but didn't are
253marked with a trailing
254?.
255<br><dt><code>debug</code> <code>[more | less | off]</code><dd>With no argument, displays the current debug level.
256Otherwise, the debug level is changed to the indicated level.
257<br><dt><code>delay</code> <kbd>milliseconds</kbd><dd>Specify a time interval to be added to timestamps included in
258requests which require authentication.
259This is used to enable
260(unreliable) server reconfiguration over long delay network paths
261or between machines whose clocks are unsynchronized.
262Actually the
263server does not now require timestamps in authenticated requests,
264so this command may be obsolete.
265<br><dt><code>exit</code><dd>Exit
266<code>ntpq</code>
267<br><dt><code>host</code> <kbd>hostname</kbd><dd>Set the host to which future queries will be sent.
268<kbd>hostname</kbd>
269may be either a host name or a numeric address.
270<br><dt><code>hostnames</code> <code>[yes | no]</code><dd>If
271<code>yes</code>
272is specified, host names are printed in
273information displays.
274If
275<code>no</code>
276is specified, numeric
277addresses are printed instead.
278The default is
279<code>yes</code>,
280unless
281modified using the command line
282<code>-n</code>
283switch.
284<br><dt><code>keyid</code> <kbd>keyid</kbd><dd>This command allows the specification of a key number to be
285used to authenticate configuration requests.
286This must correspond
287to a key number the server has been configured to use for this
288purpose.
289<br><dt><code>keytype</code> <code>[md5 | OpenSSLDigestType]</code><dd>Specify the type of key to use for authenticating requests.
290<code>md5</code>
291is alway supported.
292If
293<code>ntpq</code>
294was built with OpenSSL support,
295any digest type supported by OpenSSL can also be provided.
296If no argument is given, the current
297<code>keytype</code>
298is displayed.
299<br><dt><code>ntpversion</code> <code>[1 | 2 | 3 | 4]</code><dd>Sets the NTP version number which
300<code>ntpq</code>
301claims in
302packets.
303Defaults to 3, and note that mode 6 control messages (and
304modes, for that matter) didn't exist in NTP version 1.
305There appear
306to be no servers left which demand version 1.
307With no argument, displays the current NTP version that will be used
308when communicating with servers.
309<br><dt><code>passwd</code><dd>This command prompts you to type in a password (which will not
310be echoed) which will be used to authenticate configuration
311requests.
312The password must correspond to the key configured for
313use by the NTP server for this purpose if such requests are to be
314successful.
315<code>poll</code>
316<kbd>n</kbd>
317<code>verbose</code>
318<br><dt><code>quit</code><dd>Exit
319<code>ntpq</code>
320<br><dt><code>raw</code><dd>Causes all output from query commands is printed as received
321from the remote server.
322The only formating/interpretation done on
323the data is to transform nonascii data into a printable (but barely
324understandable) form.
325<br><dt><code>timeout</code> <kbd>milliseconds</kbd><dd>Specify a timeout period for responses to server queries.
326The
327default is about 5000 milliseconds.
328Note that since
329<code>ntpq</code>
330retries each query once after a timeout, the total waiting time for
331a timeout will be twice the timeout value set.
332<br><dt><code>version</code><dd>Print the version of the
333<code>ntpq</code>
334program.
335</dl>
336
337<h5 class="subsubsection">Control Message Commands</h5>
338
339<p>Association IDs are used to identify system, peer and clock variables.
340System variables are assigned an association ID of zero and system name space, while each association is assigned a nonzero association ID and peer namespace.
341Most control commands send a single mode-6 message to the server and expect a single response message.
342The exceptions are the
343<code>peers</code>
344command, which sends a series of messages,
345and the
346<code>mreadlist</code>
347and
348<code>mreadvar</code>
349commands, which iterate over a range of associations.
350     <dl>
351<dt><code>associations</code><dd>Display a list of mobilized associations in the form:
352     <pre class="example">          ind assid status conf reach auth condition last_event cnt
353     </pre>
354          <dl>
355<dt>Sy String Ta Sy Description<br><dt><code>ind</code> <code>Ta</code> <code>index</code> <code>on</code> <code>this</code> <code>list</code><br><dt><code>assid</code> <code>Ta</code> <code>association</code> <code>ID</code><br><dt><code>status</code> <code>Ta</code> <code>peer</code> <code>status</code> <code>word</code><br><dt><code>conf</code> <code>Ta</code> <code>yes</code>: <code>persistent,</code> <code>no</code>: <code>ephemeral</code><br><dt><code>reach</code> <code>Ta</code> <code>yes</code>: <code>reachable,</code> <code>no</code>: <code>unreachable</code><br><dt><code>auth</code> <code>Ta</code> <code>ok</code>, <code>yes</code>, <code>bad</code> <code>and</code> <code>none</code><br><dt><code>condition</code> <code>Ta</code> <code>selection</code> <code>status</code> <code>(see</code> <code>the</code> <code>select</code> <code>field</code> <code>of</code> <code>the</code> <code>peer</code> <code>status</code> <code>word)</code><br><dt><code>last_event</code> <code>Ta</code> <code>event</code> <code>report</code> <code>(see</code> <code>the</code> <code>event</code> <code>field</code> <code>of</code> <code>the</code> <code>peer</code> <code>status</code> <code>word)</code><br><dt><code>cnt</code> <code>Ta</code> <code>event</code> <code>count</code> <code>(see</code> <code>the</code> <code>count</code> <code>field</code> <code>of</code> <code>the</code> <code>peer</code> <code>status</code> <code>word)</code><dd></dl>
356     <br><dt><code>authinfo</code><dd>Display the authentication statistics.
357<br><dt><code>clockvar</code> <kbd>assocID</kbd> <code>[</code><kbd>name</kbd><code>[=</code><kbd>value</kbd><code>]]</code> <code>[...]</code><br><dt><code>cv</code> <kbd>assocID</kbd> <code>[</code><kbd>name</kbd><code>[=</code><kbd>value</kbd><code>]]</code> <code>[...]</code><dd>Display a list of clock variables for those associations supporting a reference clock.
358<br><dt><code>:config</code> <code>[...]</code><dd>Send the remainder of the command line, including whitespace, to the server as a run-time configuration command in the same format as a line in the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.
359<br><dt><code>config-from-file</code> <kbd>filename</kbd><dd>Send the each line of
360<kbd>filename</kbd>
361to the server as run-time configuration commands in the same format as a line in the configuration file. This command is experimental until further notice and clarification. Authentication is required.
362<br><dt><code>ifstats</code><dd>Display statistics for each local network address. Authentication is required.
363<br><dt><code>iostats</code><dd>Display network and reference clock I/O statistics.
364<br><dt><code>kerninfo</code><dd>Display kernel loop and PPS statistics. As with other ntpq output, times are in milliseconds. The precision value displayed is in milliseconds as well, unlike the precision system variable.
365<br><dt><code>lassociations</code><dd>Perform the same function as the associations command, except display mobilized and unmobilized associations.
366<br><dt><code>lopeers</code> <code>[-4 | -6]</code><dd>Obtain and print a list of all peers and clients showing
367<kbd>dstadr</kbd>
368(associated with any given IP version).
369<br><dt><code>lpeers</code> <code>[-4 | -6]</code><dd>Print a peer spreadsheet for the appropriate IP version(s).
370<kbd>dstadr</kbd>
371(associated with any given IP version).
372<br><dt><code>monstats</code><dd>Display monitor facility statistics.
373<br><dt><code>mrulist</code> <code>[limited | kod | mincount=</code><kbd>count</kbd><code> | laddr=</code><kbd>localaddr</kbd><code> | sort=</code><kbd>sortorder</kbd><code> | resany=</code><kbd>hexmask</kbd><code> | resall=</code><kbd>hexmask</kbd><code>]</code><dd>Obtain and print traffic counts collected and maintained by the monitor facility.
374With the exception of
375<code>sort</code>=<kbd>sortorder</kbd>,
376the options filter the list returned by
377<code>ntpd.</code>
378The
379<code>limited</code>
380and
381<code>kod</code>
382options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
383The
384<code>mincount</code>=<kbd>count</kbd>
385option filters entries representing less than
386<kbd>count</kbd>
387packets.
388The
389<code>laddr</code>=<kbd>localaddr</kbd>
390option filters entries for packets received on any local address other than
391<kbd>localaddr</kbd>.
392<code>resany</code>=<kbd>hexmask</kbd>
393and
394<code>resall</code>=<kbd>hexmask</kbd>
395filter entries containing none or less than all, respectively, of the bits in
396<kbd>hexmask</kbd>,
397which must begin with
398<code>0x</code>.
399The
400<kbd>sortorder</kbd>
401defaults to
402<code>lstint</code>
403and may be any of
404<code>addr</code>,
405<code>count</code>,
406<code>avgint</code>,
407<code>lstint</code>,
408or any of those preceded by a minus sign (hyphen) to reverse the sort order.
409The output columns are:
410          <dl>
411<dt>Column<dd>Description
412<br><dt><code>lstint</code><dd>Interval in s between the receipt of the most recent packet from this address and the completion of the retrieval of the MRU list by
413<code>ntpq</code>
414<br><dt><code>avgint</code><dd>Average interval in s between packets from this address.
415<br><dt><code>rstr</code><dd>Restriction flags associated with this address.
416Most are copied unchanged from the matching
417<code>restrict</code>
418command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
419<br><dt><code>r</code><dd>Rate control indicator, either
420a period,
421<code>L</code>
422or
423<code>K</code>
424for no rate control response,
425rate limiting by discarding, or rate limiting with a KoD response, respectively.
426<br><dt><code>m</code><dd>Packet mode.
427<br><dt><code>v</code><dd>Packet version number.
428<br><dt><code>count</code><dd>Packets received from this address.
429<br><dt><code>rport</code><dd>Source port of last packet from this address.
430<br><dt><code>remote</code> <code>address</code><dd>DNS name, numeric address, or address followed by
431claimed DNS name which could not be verified in parentheses.
432</dl>
433     <br><dt><code>mreadvar</code> <code>assocID</code> <code>assocID</code> <code>[</code><kbd>variable_name</kbd><code>[=</code><kbd>value</kbd><code>] ...]</code><br><dt><code>mrv</code> <code>assocID</code> <code>assocID</code> <code>[</code><kbd>variable_name</kbd><code>[=</code><kbd>value</kbd><code>] ...]</code><dd>Perform the same function as the
434<code>readvar</code>
435command, except for a range of association IDs.
436This range is determined from the association list cached by the most recent
437<code>associations</code>
438command.
439<br><dt><code>opeers</code> <code>[-4 | -6]</code><dd>Obtain and print the old-style list of all peers and clients showing
440<kbd>dstadr</kbd>
441(associated with any given IP version),
442rather than the
443<kbd>refid</kbd>.
444<br><dt><code>passociations</code><dd>Perform the same function as the
445<code>associations</code>
446command,
447except that it uses previously stored data rather than making a new query.
448<br><dt><code>peers</code><dd>Display a list of peers in the form:
449     <pre class="example">          [tally]remote refid st t when pool reach delay offset jitter
450     </pre>
451          <dl>
452<dt>Variable<dd>Description
453<br><dt><code>[tally]</code><dd>single-character code indicating current value of the
454<code>select</code>
455field of the
456.Lk decode.html#peer "peer status word"
457<br><dt><code>remote</code><dd>host name (or IP number) of peer.
458The value displayed will be truncated to 15 characters  unless the
459<code>-w</code>
460flag is given, in which case the full value will be displayed
461on the first line,
462and the remaining data is displayed on the next line.
463<br><dt><code>refid</code><dd>association ID or
464.Lk decode.html#kiss "'kiss code"
465<br><dt><code>st</code><dd>stratum
466<br><dt><code>t</code><dd><code>u</code>:
467unicast or manycast client,
468<code>b</code>:
469broadcast or multicast client,
470<code>l</code>:
471local (reference clock),
472<code>s</code>:
473symmetric (peer),
474<code>A</code>:
475manycast server,
476<code>B</code>:
477broadcast server,
478<code>M</code>:
479multicast server
480<br><dt><code>when</code><dd>sec/min/hr since last received packet
481<br><dt><code>poll</code><dd>poll interval (log2 s)
482<br><dt><code>reach</code><dd>reach shift register (octal)
483<br><dt><code>delay</code><dd>roundtrip delay
484<br><dt><code>offset</code><dd>offset of server relative to this host
485<br><dt><code>jitter</code><dd>jitter
486</dl>
487     <br><dt><code>pstats</code> <kbd>assocID</kbd><dd>Show the statistics for the peer with the given
488<kbd>assocID</kbd>.
489<br><dt><code>readlist</code> <kbd>assocID</kbd><br><dt><code>rl</code> <kbd>assocID</kbd><dd>Read the system or peer variables included in the variable list.
490<br><dt><code>readvar</code> <kbd>assocID</kbd> <kbd>name</kbd><code>[=</code><kbd>value</kbd><code>]</code> <code>[, ...]</code><br><dt><code>rv</code> <kbd>assocID</kbd> <kbd>name</kbd><code>[=</code><kbd>value</kbd><code>]</code> <code>[, ...]</code><dd>Display the specified variables.
491If
492<kbd>assocID</kbd>
493is zero, the variables are from the
494<a href="#System-Variables">System Variables</a>
495name space, otherwise they are from the
496<a href="#Peer-Variables">Peer Variables</a>
497name space.
498The
499<kbd>assocID</kbd>
500is required, as the same name can occur in both spaces.
501If no
502<kbd>name</kbd>
503is included, all operative variables in the name space are displayed.
504
505     <p>In this case only, if the
506<kbd>assocID</kbd>
507is omitted, it is assumed zero.
508Multiple names are specified with comma separators and without whitespace.
509Note that time values are represented in milliseconds
510and frequency values in parts-per-million (PPM).
511Some NTP timestamps are represented in the format
512YYYYMMDDTTTT ,
513where YYYY is the year,
514MM the month of year,
515DD the day of month and
516TTTT the time of day.
517<br><dt><code>reslist</code><dd>Show the access control (restrict) list for
518<code>ntpq</code>
519
520     <br><dt><code>saveconfig</code> <kbd>filename</kbd><dd>Write the current configuration,
521including any runtime modifications given with
522<code>:config</code>
523or
524<code>config-from-file</code>,
525to the ntpd host's file
526<kbd>filename</kbd>.
527This command will be rejected by the server unless
528.Lk miscopt.html#saveconfigdir "saveconfigdir"
529appears in the
530<code>ntpd</code>
531configuration file.
532<kbd>filename</kbd>
533can use
534<code>strftime()</code>
535format specifies to substitute the current date and time, for example,
536<code>q]saveconfig</code> <code>ntp-%Y%m%d-%H%M%S.confq]</code>.
537The filename used is stored in system variable
538<code>savedconfig</code>.
539Authentication is required.
540<br><dt><code>timerstats</code><dd>Display interval timer counters.
541<br><dt><code>writelist</code> <kbd>assocID</kbd><dd>Write the system or peer variables included in the variable list.
542<br><dt><code>writevar</code> <kbd>assocID</kbd> <kbd>name</kbd>=<kbd>value</kbd> <code>[, ...]</code><dd>Write the specified variables.
543If the
544<kbd>assocID</kbd>
545is zero, the variables are from the
546<a href="#System-Variables">System Variables</a>
547name space, otherwise they are from the
548<a href="#Peer-Variables">Peer Variables</a>
549name space.
550The
551<kbd>assocID</kbd>
552is required, as the same name can occur in both spaces.
553<br><dt><code>sysinfo</code><dd>Display operational summary.
554<br><dt><code>sysstats</code><dd>Print statistics counters maintained in the protocol module.
555</dl>
556
557<h5 class="subsubsection">Status Words and Kiss Codes</h5>
558
559<p>The current state of the operating program is shown
560in a set of status words
561maintained by the system.
562Status information is also available on a per-association basis.
563These words are displayed in the
564<code>rv</code>
565and
566<code>as</code>
567commands both in hexadecimal and in decoded short tip strings.
568The codes, tips and short explanations are documented on the
569.Lk decode.html "Event Messages and Status Words"
570page.
571The page also includes a list of system and peer messages,
572the code for the latest of which is included in the status word.
573
574  <p>Information resulting from protocol machine state transitions
575is displayed using an informal set of ASCII strings called
576.Lk decode.html#kiss "kiss codes" .
577The original purpose was for kiss-o'-death (KoD) packets
578sent by the server to advise the client of an unusual condition.
579They are now displayed, when appropriate,
580in the reference identifier field in various billboards.
581
582<h5 class="subsubsection">System Variables</h5>
583
584<p>The following system variables appear in the
585<code>rv</code>
586billboard.
587Not all variables are displayed in some configurations.
588     <dl>
589<dt>Variable<dd>Description
590<br><dt><code>status</code><dd>.Lk decode.html#sys "system status word"
591<br><dt><code>version</code><dd>NTP software version and build time
592<br><dt><code>processor</code><dd>hardware platform and version
593<br><dt><code>system</code><dd>operating system and version
594<br><dt><code>leap</code><dd>leap warning indicator (0-3)
595<br><dt><code>stratum</code><dd>stratum (1-15)
596<br><dt><code>precision</code><dd>precision (log2 s)
597<br><dt><code>rootdelay</code><dd>total roundtrip delay to the primary reference clock
598<br><dt><code>rootdisp</code><dd>total dispersion to the primary reference clock
599<br><dt><code>peer</code><dd>system peer association ID
600<br><dt><code>tc</code><dd>time constant and poll exponent (log2 s) (3-17)
601<br><dt><code>mintc</code><dd>minimum time constant (log2 s) (3-10)
602<br><dt><code>clock</code><dd>date and time of day
603<br><dt><code>refid</code><dd>reference ID or
604.Lk decode.html#kiss "kiss code"
605<br><dt><code>reftime</code><dd>reference time
606<br><dt><code>offset</code><dd>combined  offset of server relative to this host
607<br><dt><code>sys_jitter</code><dd>combined system jitter
608<br><dt><code>frequency</code><dd>frequency offset (PPM) relative to hardware clock
609<br><dt><code>clk_wander</code><dd>clock frequency wander (PPM)
610<br><dt><code>clk_jitter</code><dd>clock jitter
611<br><dt><code>tai</code><dd>TAI-UTC offset (s)
612<br><dt><code>leapsec</code><dd>NTP seconds when the next leap second is/was inserted
613<br><dt><code>expire</code><dd>NTP seconds when the NIST leapseconds file expires
614</dl>
615  The jitter and wander statistics are exponentially-weighted RMS averages.
616The system jitter is defined in the NTPv4 specification;
617the clock jitter statistic is computed by the clock discipline module.
618
619  <p>When the NTPv4 daemon is compiled with the OpenSSL software library,
620additional system variables are displayed,
621including some or all of the following,
622depending on the particular Autokey dance:
623
624     <dl>
625<dt>Variable<dd>Description
626<br><dt><code>host</code><dd>Autokey host name for this host
627<br><dt><code>ident</code><dd>Autokey group name for this host
628<br><dt><code>flags</code><dd>host flags  (see Autokey specification)
629<br><dt><code>digest</code><dd>OpenSSL message digest algorithm
630<br><dt><code>signature</code><dd>OpenSSL digest/signature scheme
631<br><dt><code>update</code><dd>NTP seconds at last signature update
632<br><dt><code>cert</code><dd>certificate subject, issuer and certificate flags
633<br><dt><code>until</code><dd>NTP seconds when the certificate expires
634</dl>
635
636<h5 class="subsubsection">Peer Variables</h5>
637
638<p>The following peer variables appear in the
639<code>rv</code>
640billboard for each association.
641Not all variables are displayed in some configurations.
642
643     <dl>
644<dt>Variable<dd>Description
645<br><dt><code>associd</code><dd>association ID
646<br><dt><code>status</code><dd>.Lk decode.html#peer "peer status word"
647<br><dt><code>srcadr</code><dd>source (remote) IP address
648<br><dt><code>srcport</code><dd>source (remote) port
649<br><dt><code>dstadr</code><dd>destination (local) IP address
650<br><dt><code>dstport</code><dd>destination (local) port
651<br><dt><code>leap</code><dd>leap indicator (0-3)
652<br><dt><code>stratum</code><dd>stratum (0-15)
653<br><dt><code>precision</code><dd>precision (log2 s)
654<br><dt><code>rootdelay</code><dd>total roundtrip delay to the primary reference clock
655<br><dt><code>rootdisp</code><dd>total root dispersion to the primary reference clock
656<br><dt><code>refid</code><dd>reference ID or
657.Lk decode.html#kiss "kiss code"
658<br><dt><code>reftime</code><dd>reference time
659<br><dt><code>reach</code><dd>reach register (octal)
660<br><dt><code>unreach</code><dd>unreach counter
661<br><dt><code>hmode</code><dd>host mode (1-6)
662<br><dt><code>pmode</code><dd>peer mode (1-5)
663<br><dt><code>hpoll</code><dd>host poll exponent (log2 s) (3-17)
664<br><dt><code>ppoll</code><dd>peer poll exponent (log2 s) (3-17)
665<br><dt><code>headway</code><dd>headway (see
666.Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
667<br><dt><code>flash</code><dd>.Lk decode.html#flash "flash status word"
668<br><dt><code>offset</code><dd>filter offset
669<br><dt><code>delay</code><dd>filter delay
670<br><dt><code>dispersion</code><dd>filter dispersion
671<br><dt><code>jitter</code><dd>filter jitter
672<br><dt><code>ident</code><dd>Autokey group name for this association
673<br><dt><code>bias</code><dd>unicast/broadcast bias
674<br><dt><code>xleave</code><dd>interleave delay (see
675.Lk xleave.html "NTP Interleaved Modes" )
676</dl>
677  The
678<code>bias</code>
679variable is calculated when the first broadcast packet is received
680after the calibration volley.
681It represents the offset of the broadcast subgraph relative to the unicast subgraph.
682The
683<code>xleave</code>
684variable appears only for the interleaved symmetric and interleaved modes.
685It represents the internal queuing, buffering and transmission delays
686for the preceding packet.
687
688  <p>When the NTPv4 daemon is compiled with the OpenSSL software library,
689additional peer variables are displayed, including the following:
690     <dl>
691<dt>Variable<dd>Description
692<br><dt><code>flags</code><dd>peer flags (see Autokey specification)
693<br><dt><code>host</code><dd>Autokey server name
694<br><dt><code>flags</code><dd>peer flags (see Autokey specification)
695<br><dt><code>signature</code><dd>OpenSSL digest/signature scheme
696<br><dt><code>initsequence</code><dd>initial key ID
697<br><dt><code>initkey</code><dd>initial key index
698<br><dt><code>timestamp</code><dd>Autokey signature timestamp
699</dl>
700
701<h5 class="subsubsection">Clock Variables</h5>
702
703<p>The following clock variables appear in the
704<code>cv</code>
705billboard for each association with a reference clock.
706Not all variables are displayed in some configurations.
707     <dl>
708<dt>Variable<dd>Description
709<br><dt><code>associd</code><dd>association ID
710<br><dt><code>status</code><dd>.Lk decode.html#clock "clock status word"
711<br><dt><code>device</code><dd>device description
712<br><dt><code>timecode</code><dd>ASCII time code string (specific to device)
713<br><dt><code>poll</code><dd>poll messages sent
714<br><dt><code>noreply</code><dd>no reply
715<br><dt><code>badformat</code><dd>bad format
716<br><dt><code>baddata</code><dd>bad date or time
717<br><dt><code>fudgetime1</code><dd>fudge time 1
718<br><dt><code>fudgetime2</code><dd>fudge time 2
719<br><dt><code>stratum</code><dd>driver stratum
720<br><dt><code>refid</code><dd>driver reference ID
721<br><dt><code>flags</code><dd>driver flags
722</dl>
723
724  <p>This section was generated by <strong>AutoGen</strong>,
725using the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntpq</code> program.
726This software is released under the NTP license, &lt;http://ntp.org/license&gt;.
727
728<ul class="menu">
729<li><a accesskey="1" href="#ntpq-usage">ntpq usage</a>:                   ntpq help/usage (<span class="option">--help</span>)
730<li><a accesskey="2" href="#ntpq-ipv4">ntpq ipv4</a>:                    ipv4 option (-4)
731<li><a accesskey="3" href="#ntpq-ipv6">ntpq ipv6</a>:                    ipv6 option (-6)
732<li><a accesskey="4" href="#ntpq-command">ntpq command</a>:                 command option (-c)
733<li><a accesskey="5" href="#ntpq-interactive">ntpq interactive</a>:             interactive option (-i)
734<li><a accesskey="6" href="#ntpq-numeric">ntpq numeric</a>:                 numeric option (-n)
735<li><a accesskey="7" href="#ntpq-old_002drv">ntpq old-rv</a>:                  old-rv option
736<li><a accesskey="8" href="#ntpq-peers">ntpq peers</a>:                   peers option (-p)
737<li><a accesskey="9" href="#ntpq-wide">ntpq wide</a>:                    wide option (-w)
738<li><a href="#ntpq-config">ntpq config</a>:                  presetting/configuring ntpq
739<li><a href="#ntpq-exit-status">ntpq exit status</a>:             exit status
740</ul>
741
742<div class="node">
743<p><hr>
744<a name="ntpq-usage"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-ipv4">ntpq ipv4</a>,
745Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
746<br>
747</div>
748
749<h4 class="subsection">ntpq help/usage (<span class="option">--help</span>)</h4>
750
751<p><a name="index-ntpq-help-3"></a>
752This is the automatically generated usage text for ntpq.
753
754  <p>The text printed is the same whether selected with the <code>help</code> option
755(<span class="option">--help</span>) or the <code>more-help</code> option (<span class="option">--more-help</span>).  <code>more-help</code> will print
756the usage text by passing it through a pager program.
757<code>more-help</code> is disabled on platforms without a working
758<code>fork(2)</code> function.  The <code>PAGER</code> environment variable is
759used to select the program, defaulting to <span class="file">more</span>.  Both will exit
760with a status code of 0.
761
762<pre class="example">ntpq - standard NTP query program - Ver. 4.2.8p2-RC3
763Usage:  ntpq [ -&lt;flag&gt; [&lt;val&gt;] | --&lt;name&gt;[{=| }&lt;val&gt;] ]... [ host ...]
764  Flg Arg Option-Name    Description
765   -4 no  ipv4           Force IPv4 DNS name resolution
766                                - prohibits the option 'ipv6'
767   -6 no  ipv6           Force IPv6 DNS name resolution
768                                - prohibits the option 'ipv4'
769   -c Str command        run a command and exit
770                                - may appear multiple times
771   -d no  debug-level    Increase debug verbosity level
772                                - may appear multiple times
773   -D Num set-debug-level Set the debug verbosity level
774                                - may appear multiple times
775   -i no  interactive    Force ntpq to operate in interactive mode
776                                - prohibits these options:
777                                command
778                                peers
779   -n no  numeric        numeric host addresses
780      no  old-rv         Always output status line with readvar
781   -p no  peers          Print a list of the peers
782                                - prohibits the option 'interactive'
783   -w no  wide           Display the full 'remote' value
784      opt version        output version information and exit
785   -? no  help           display extended usage information and exit
786   -! no  more-help      extended usage information passed thru pager
787   -&gt; opt save-opts      save the option state to a config file
788   -&lt; Str load-opts      load options from a config file
789                                - disabled as '--no-load-opts'
790                                - may appear multiple times
791
792Options are specified by doubled hyphens and their name or by a single
793hyphen and the flag character.
794
795The following option preset mechanisms are supported:
796 - reading file $HOME/.ntprc
797 - reading file ./.ntprc
798 - examining environment variables named NTPQ_*
799
800Please send bug reports to:  &lt;http://bugs.ntp.org, bugs@ntp.org&gt;
801</pre>
802  <div class="node">
803<p><hr>
804<a name="ntpq-ipv4"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-ipv6">ntpq ipv6</a>,
805Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-usage">ntpq usage</a>,
806Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
807<br>
808</div>
809
810<h4 class="subsection">ipv4 option (-4)</h4>
811
812<p><a name="index-ntpq_002dipv4-4"></a>
813This is the &ldquo;force ipv4 dns name resolution&rdquo; option.
814
815<p class="noindent">This option has some usage constraints.  It:
816     <ul>
817<li>must not appear in combination with any of the following options:
818ipv6.
819</ul>
820
821  <p>Force DNS resolution of following host names on the command line
822to the IPv4 namespace.
823<div class="node">
824<p><hr>
825<a name="ntpq-ipv6"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-command">ntpq command</a>,
826Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-ipv4">ntpq ipv4</a>,
827Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
828<br>
829</div>
830
831<h4 class="subsection">ipv6 option (-6)</h4>
832
833<p><a name="index-ntpq_002dipv6-5"></a>
834This is the &ldquo;force ipv6 dns name resolution&rdquo; option.
835
836<p class="noindent">This option has some usage constraints.  It:
837     <ul>
838<li>must not appear in combination with any of the following options:
839ipv4.
840</ul>
841
842  <p>Force DNS resolution of following host names on the command line
843to the IPv6 namespace.
844<div class="node">
845<p><hr>
846<a name="ntpq-command"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-interactive">ntpq interactive</a>,
847Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-ipv6">ntpq ipv6</a>,
848Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
849<br>
850</div>
851
852<h4 class="subsection">command option (-c)</h4>
853
854<p><a name="index-ntpq_002dcommand-6"></a>
855This is the &ldquo;run a command and exit&rdquo; option.
856This option takes a string argument <span class="file">cmd</span>.
857
858<p class="noindent">This option has some usage constraints.  It:
859     <ul>
860<li>may appear an unlimited number of times.
861</ul>
862
863  <p>The following argument is interpreted as an interactive format command
864and is added to the list of commands to be executed on the specified
865host(s).
866<div class="node">
867<p><hr>
868<a name="ntpq-interactive"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-numeric">ntpq numeric</a>,
869Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-command">ntpq command</a>,
870Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
871<br>
872</div>
873
874<h4 class="subsection">interactive option (-i)</h4>
875
876<p><a name="index-ntpq_002dinteractive-7"></a>
877This is the &ldquo;force ntpq to operate in interactive mode&rdquo; option.
878
879<p class="noindent">This option has some usage constraints.  It:
880     <ul>
881<li>must not appear in combination with any of the following options:
882command, peers.
883</ul>
884
885  <p>Force <code>ntpq</code> to operate in interactive mode.
886Prompts will be written to the standard output and
887commands read from the standard input.
888<div class="node">
889<p><hr>
890<a name="ntpq-numeric"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-old_002drv">ntpq old-rv</a>,
891Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-interactive">ntpq interactive</a>,
892Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
893<br>
894</div>
895
896<h4 class="subsection">numeric option (-n)</h4>
897
898<p><a name="index-ntpq_002dnumeric-8"></a>
899This is the &ldquo;numeric host addresses&rdquo; option.
900Output all host addresses in dotted-quad numeric format rather than
901converting to the canonical host names.
902<div class="node">
903<p><hr>
904<a name="ntpq-old_002drv"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-peers">ntpq peers</a>,
905Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-numeric">ntpq numeric</a>,
906Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
907<br>
908</div>
909
910<h4 class="subsection">old-rv option</h4>
911
912<p><a name="index-ntpq_002dold_002drv-9"></a>
913This is the &ldquo;always output status line with readvar&rdquo; option.
914By default, <code>ntpq</code> now suppresses the <code>associd=...</code>
915line that precedes the output of <code>readvar</code>
916(alias <code>rv</code>) when a single variable is requested, such as
917<code>ntpq -c "rv 0 offset"</code>.
918This option causes <code>ntpq</code> to include both lines of output
919for a single-variable <code>readvar</code>.
920Using an environment variable to
921preset this option in a script will enable both older and
922newer <code>ntpq</code> to behave identically in this regard.
923<div class="node">
924<p><hr>
925<a name="ntpq-peers"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-wide">ntpq wide</a>,
926Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-old_002drv">ntpq old-rv</a>,
927Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
928<br>
929</div>
930
931<h4 class="subsection">peers option (-p)</h4>
932
933<p><a name="index-ntpq_002dpeers-10"></a>
934This is the &ldquo;print a list of the peers&rdquo; option.
935
936<p class="noindent">This option has some usage constraints.  It:
937     <ul>
938<li>must not appear in combination with any of the following options:
939interactive.
940</ul>
941
942  <p>Print a list of the peers known to the server as well as a summary
943of their state. This is equivalent to the 'peers' interactive command.
944<div class="node">
945<p><hr>
946<a name="ntpq-wide"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-config">ntpq config</a>,
947Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-peers">ntpq peers</a>,
948Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
949<br>
950</div>
951
952<h4 class="subsection">wide option (-w)</h4>
953
954<p><a name="index-ntpq_002dwide-11"></a>
955This is the &ldquo;display the full 'remote' value&rdquo; option.
956Display the full value of the 'remote' value.  If this requires
957more than 15 characters, display the full value, emit a newline,
958and continue the data display properly indented on the next line.
959
960<div class="node">
961<p><hr>
962<a name="ntpq-config"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#ntpq-exit-status">ntpq exit status</a>,
963Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-wide">ntpq wide</a>,
964Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
965<br>
966</div>
967
968<h4 class="subsection">presetting/configuring ntpq</h4>
969
970<p>Any option that is not marked as <i>not presettable</i> may be preset by
971loading values from configuration ("rc" or "ini") files, and values from environment variables named <code>NTPQ</code> and <code>NTPQ_&lt;OPTION_NAME&gt;</code>.  <code>&lt;OPTION_NAME&gt;</code> must be one of
972the options listed above in upper case and segmented with underscores.
973The <code>NTPQ</code> variable will be tokenized and parsed like
974the command line.  The remaining variables are tested for existence and their
975values are treated like option arguments.
976
977<p class="noindent"><code>libopts</code> will search in 2 places for configuration files:
978     <ul>
979<li>$HOME
980<li>$PWD
981</ul>
982  The environment variables <code>HOME</code>, and <code>PWD</code>
983are expanded and replaced when <span class="file">ntpq</span> runs.
984For any of these that are plain files, they are simply processed.
985For any that are directories, then a file named <span class="file">.ntprc</span> is searched for
986within that directory and processed.
987
988  <p>Configuration files may be in a wide variety of formats.
989The basic format is an option name followed by a value (argument) on the
990same line.  Values may be separated from the option name with a colon,
991equal sign or simply white space.  Values may be continued across multiple
992lines by escaping the newline with a backslash.
993
994  <p>Multiple programs may also share the same initialization file.
995Common options are collected at the top, followed by program specific
996segments.  The segments are separated by lines like:
997<pre class="example">    [NTPQ]
998</pre>
999  <p class="noindent">or by
1000<pre class="example">    &lt;?program ntpq&gt;
1001</pre>
1002  <p class="noindent">Do not mix these styles within one configuration file.
1003
1004  <p>Compound values and carefully constructed string values may also be
1005specified using XML syntax:
1006<pre class="example">    &lt;option-name&gt;
1007       &lt;sub-opt&gt;...&amp;lt;...&amp;gt;...&lt;/sub-opt&gt;
1008    &lt;/option-name&gt;
1009</pre>
1010  <p class="noindent">yielding an <code>option-name.sub-opt</code> string value of
1011<pre class="example">    "...&lt;...&gt;..."
1012</pre>
1013  <p><code>AutoOpts</code> does not track suboptions.  You simply note that it is a
1014hierarchicly valued option.  <code>AutoOpts</code> does provide a means for searching
1015the associated name/value pair list (see: optionFindValue).
1016
1017  <p>The command line options relating to configuration and/or usage help are:
1018
1019<h5 class="subsubheading">version (-)</h5>
1020
1021<p>Print the program version to standard out, optionally with licensing
1022information, then exit 0.  The optional argument specifies how much licensing
1023detail to provide.  The default is to print just the version.  The licensing infomation may be selected with an option argument.
1024Only the first letter of the argument is examined:
1025
1026     <dl>
1027<dt><span class="samp">version</span><dd>Only print the version.  This is the default.
1028<br><dt><span class="samp">copyright</span><dd>Name the copyright usage licensing terms.
1029<br><dt><span class="samp">verbose</span><dd>Print the full copyright usage licensing terms.
1030</dl>
1031
1032<div class="node">
1033<p><hr>
1034<a name="ntpq-exit-status"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-config">ntpq config</a>,
1035Up:&nbsp;<a rel="up" accesskey="u" href="#ntpq-Invocation">ntpq Invocation</a>
1036<br>
1037</div>
1038
1039<h4 class="subsection">ntpq exit status</h4>
1040
1041<p>One of the following exit values will be returned:
1042     <dl>
1043<dt><span class="samp">0 (EXIT_SUCCESS)</span><dd>Successful program execution.
1044<br><dt><span class="samp">1 (EXIT_FAILURE)</span><dd>The operation failed or the command syntax was not valid.
1045<br><dt><span class="samp">66 (EX_NOINPUT)</span><dd>A specified configuration file could not be loaded.
1046<br><dt><span class="samp">70 (EX_SOFTWARE)</span><dd>libopts had an internal operational error.  Please report
1047it to autogen-users@lists.sourceforge.net.  Thank you.
1048</dl>
1049
1050<div class="node">
1051<p><hr>
1052<a name="Usage"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Internal-Commands">Internal Commands</a>,
1053Previous:&nbsp;<a rel="previous" accesskey="p" href="#ntpq-Description">ntpq Description</a>,
1054Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1055<br>
1056</div>
1057
1058<!-- node-name,  next,  previous,  up -->
1059<h3 class="section">Usage</h3>
1060
1061<p><table summary=""><tr align="left"><th valign="top" width="23%">What </th><th valign="top" width="23%">Default </th><th valign="top" width="5%">Flag </th><th valign="top" width="15%">Option
1062<br></th></tr><tr align="left"><td valign="top" width="23%">configuration file
1063</td><td valign="top" width="23%"><code>/etc/ntp.conf</code>
1064</td><td valign="top" width="5%"><code>-c</code>
1065</td><td valign="top" width="15%"><code>conffile</code>
1066<br></td></tr><tr align="left"><td valign="top" width="23%">frequency file
1067</td><td valign="top" width="23%">none
1068</td><td valign="top" width="5%"><code>-f</code>
1069</td><td valign="top" width="15%"><code>driftfile</code>
1070<br></td></tr><tr align="left"><td valign="top" width="23%">leapseconds file
1071</td><td valign="top" width="23%">none
1072</td><td valign="top" width="5%">
1073</td><td valign="top" width="15%"><code>leapfile</code>
1074<br></td></tr><tr align="left"><td valign="top" width="23%">process ID file
1075</td><td valign="top" width="23%">none
1076</td><td valign="top" width="5%"><code>-p</code>
1077</td><td valign="top" width="15%"><code>pidfile</code>
1078<br></td></tr><tr align="left"><td valign="top" width="23%">log file
1079</td><td valign="top" width="23%">system log
1080</td><td valign="top" width="5%"><code>-l</code>
1081</td><td valign="top" width="15%"><code>logfile</code>
1082<br></td></tr><tr align="left"><td valign="top" width="23%">include file
1083</td><td valign="top" width="23%">none
1084</td><td valign="top" width="5%">none
1085</td><td valign="top" width="15%"><code>includefile</code>
1086<br></td></tr><tr align="left"><td valign="top" width="23%">statistics path
1087</td><td valign="top" width="23%"><code>/var/NTP</code>
1088</td><td valign="top" width="5%"><code>-s</code>
1089</td><td valign="top" width="15%"><code>statsdir</code>
1090<br></td></tr><tr align="left"><td valign="top" width="23%">keys path
1091</td><td valign="top" width="23%"><code>/usr/local/etc</code>
1092</td><td valign="top" width="5%"><code>-k</code>
1093</td><td valign="top" width="15%"><code>keysdir</code>
1094<br></td></tr></table>
1095
1096<div class="node">
1097<p><hr>
1098<a name="Internal-Commands"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Control-Message-Commands">Control Message Commands</a>,
1099Previous:&nbsp;<a rel="previous" accesskey="p" href="#Usage">Usage</a>,
1100Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1101<br>
1102</div>
1103
1104<!-- node-name,  next,  previous,  up -->
1105<h3 class="section">Internal Commands</h3>
1106
1107<p>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>&gt;</code>, followed by a file name, to the command line.  A number of interactive format commands are executed entirely within the <code>ntpq</code> program itself and do not result in NTP mode-6 requests being sent to a server.  These are described following.
1108
1109     <dl>
1110<dt><code><a name="help"></a> ? [</code><kbd>command_keyword</kbd><code>]</code><dt><code>help [</code><kbd>command_keyword</kbd><code>]</code><dd>A <code>?</code> by itself will print a list of all the command keywords known to <code>ntpq</code>.  A <code>?</code> followed by a command keyword will print function and usage information about the command.
1111
1112     <br><dt><code><a name="addvars"></a> &gt;addvars </code><kbd>name</kbd><code> [ = </code><kbd>value</kbd><code>] [...]</code><dt><code>rmvars </code><kbd>name</kbd><code> [...]</code><dt><code>clearvars&lt;/dt&gt;</code><dd>The arguments to these commands consist of a list of items of the form
1113<kbd>name</kbd><code> = </code><kbd>value</kbd>, where the <code>= </code><kbd>value</kbd> is ignored,
1114and can be omitted in read requests.
1115<code>ntpq</code> maintains an internal list in which data to be included
1116in control messages can be assembled, and sent using the <code>readlist</code>
1117and <code>writelist</code> commands described below.
1118The <code>addvars</code> command allows variables and optional values
1119to be added to the list.
1120If more than one variable is to be added
1121the list should be comma-separated and not contain white space.
1122The <code>rmvars</code> command can be used to remove individual variables
1123from the list,
1124while the <code>clearlist</code> command removes all variables from the list.
1125
1126     <br><dt><code><a name="cooked"></a> cooked</code><dd>Display server messages in prettyprint format.
1127
1128     <br><dt><code><a name="debug"></a> debug more | less | off</code><dd>Turns internal query program debugging on and off.
1129
1130     <br><dt><code><a name="delay"></a> delay </code><kbd>milliseconds</kbd><dd>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.
1131
1132     <br><dt><code><a name="host"></a> host </code><kbd>name</kbd><dd>Set the host to which future queries will be sent.
1133The name may be either a DNS name or a numeric address.
1134
1135     <br><dt><code><a name="hostnames"></a> hostnames [yes | no]</code><dd>If <code>yes</code> is specified, host names are printed in information displays.
1136If <code>no</code> is specified, numeric addresses are printed instead.
1137The default is <code>yes</code>,
1138unless modified using the command line <code>-n</code> switch.
1139
1140     <br><dt><code><a name="keyid"></a> keyid </code><kbd>keyid</kbd><dd>This command specifies the key number to be used
1141to authenticate configuration requests.
1142This must correspond to a key ID configured in <code>ntp.conf</code> for this purpose.
1143
1144     <br><dt><code><a name="keytype"></a> keytype</code><dd>Specify the digest algorithm to use for authenticated requests,
1145with default <code>MD5</code>.
1146If the OpenSSL library is installed,
1147digest can be be any message digest algorithm supported by the library.
1148The current selections are: <code>MD2</code>, <code>MD4</code>, <code>MD5</code>, <code>MDC2</code>, <code>RIPEMD160</code>, <code>SHA</code> and <code>SHA1</code>.
1149
1150     <br><dt><code><a name="ntpversion"></a> ntpversion 1 | 2 | 3 | 4</code><dd>Sets the NTP version number which <code>ntpq</code> claims in packets.
1151Defaults to 2.
1152Note that mode-6 control messages (and modes, for that matter)
1153didn't exist in NTP version 1.
1154
1155     <br><dt><code><a name="passwd"></a> passwd</code><dd>This command prompts for a password to authenticate requests.
1156The password must correspond to the key ID configured in <code>ntp.conf</code> for this purpose.
1157
1158     <br><dt><code><a name="quit"></a> quit</code><dd>Exit <code>ntpq</code>.
1159
1160     <br><dt><code><a name="raw"></a> raw</code><dd>Display server messages as received and without reformatting.
1161
1162     <br><dt><code><a name="timeout"></a> timeout </code><kbd>millseconds</kbd><dd>Specify a timeout period for responses to server queries.
1163The default is about 5000 milliseconds.
1164Note that since <code>ntpq</code> retries each query once after a timeout
1165the total waiting time for a timeout will be twice the timeout value set.
1166
1167  </dl>
1168
1169<div class="node">
1170<p><hr>
1171<a name="Control-Message-Commands"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Status-Words-and-Kiss-Codes">Status Words and Kiss Codes</a>,
1172Previous:&nbsp;<a rel="previous" accesskey="p" href="#Internal-Commands">Internal Commands</a>,
1173Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1174<br>
1175</div>
1176
1177<!-- node-name,  next,  previous,  up -->
1178<h3 class="section">Control Message Commands</h3>
1179
1180<p>Association IDs are used to identify system, peer and clock variables.
1181System variables are assigned an association ID of zero and system name space,
1182while each association is assigned a nonzero association ID and peer namespace.
1183Most control commands send a single mode-6 message to the server
1184and expect a single response message.
1185The exceptions are the <code>peers</code> command,
1186which sends a series of messages,
1187and the <code>mreadlist</code> and <code>mreadvar</code> commands,
1188which iterate over a range of associations.
1189
1190  <p><a name="as"></a>
1191     <dl>
1192<dt><code>associations</code><dd>Display a list of mobilized associations in the form:
1193<br>
1194<code>ind assid status conf reach auth condition last_event cnt</code>
1195
1196     <p><table summary=""><tr align="left"><th valign="top" width="10%">Variable </th><th valign="top" width="40%">Description
1197
1198     <p><br></th></tr><tr align="left"><td valign="top" width="10%"><code>ind</code>
1199</td><td valign="top" width="40%">index on this list
1200
1201     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>assid</code>
1202</td><td valign="top" width="40%">association ID
1203
1204     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>status</code>
1205</td><td valign="top" width="40%"><a href="decode.html#peer">peer status word</a>
1206
1207     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>conf</code>
1208</td><td valign="top" width="40%"><code>yes</code>: persistent, <code>no</code>: ephemeral
1209
1210     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>reach</code>
1211</td><td valign="top" width="40%"><code>yes</code>: reachable, <code>no</code>: unreachable
1212
1213     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>auth</code>
1214</td><td valign="top" width="40%"><code>ok</code>, <code>yes</code>, <code>bad</code> and <code>none</code>
1215
1216     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>condition</code>
1217</td><td valign="top" width="40%">selection status (see the <code>select</code> field of the <a href="decode.html#peer">peer status word</a>)
1218
1219     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>last_event</code>
1220</td><td valign="top" width="40%">event report (see the <code>event</code> field of the <a href="decode.html#peer">peer status word</a>)
1221
1222     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>cnt</code>
1223event count (see the <code>count</code> field of the <a href="decode.html#peer">peer status word</a>)
1224
1225     <br></td></tr></table>
1226
1227     <br><dt><code><a name="cv"></a> clockvar </code><kbd>assocID</kbd><code> [</code><kbd>name</kbd><code> [ = </code><kbd>value</kbd><code> [...]] [...]]</code><dt><code>cv </code><kbd>assocID</kbd><code> [</code><kbd>name</kbd><code> [ = </code><kbd>value</kbd><code> [...] ][...]]</code><dd>Display a list of <a href="#clock">clock variables</a> for those associations supporting a reference clock.
1228
1229     <br><dt><code><a name="_003aconfig"></a> :config [...]</code><dd>Send the remainder of the command line, including whitespace, to the server
1230as a run-time configuration command in the same format
1231as the configuration file.
1232This command is experimental until further notice and clarification.
1233Authentication is of course required.
1234
1235     <br><dt><code><a name="config_002dfrom_002dfile"></a> config-from-file </code><kbd>filename</kbd><dd>Send the each line of <kbd>filename</kbd> to the server as
1236run-time configuration commands in the same format as the configuration file.
1237This command is experimental until further notice and clarification.
1238Authentication is required.
1239
1240     <br><dt><code><a name="ifstats"></a> ifstats</code><dd>Display statistics for each local network address.
1241Authentication is required.
1242
1243     <br><dt><code><a name="iostats"></a> iostats</code><dd>Display network and reference clock I/O statistics.
1244
1245     <br><dt><code><a name="kerninfo"></a> kerninfo</code><dd>Display kernel loop and PPS statistics.
1246As with other ntpq output, times are in milliseconds.
1247The precision value displayed is in milliseconds as well,
1248unlike the precision system variable.
1249
1250     <br><dt><code><a name="lassoc"></a> lassociations</code><dd>Perform the same function as the associations command,
1251except display mobilized and unmobilized associations.
1252
1253     <br><dt><code><a name="monstats"></a> monstats</code><dd>Display monitor facility statistics.
1254
1255     <br><dt><code><a name="mrulist"></a> mrulist [limited | kod | mincount=</code><kbd>count</kbd><code> | laddr=</code><kbd>localaddr</kbd><code> | sort=</code><kbd>sortorder</kbd><code> | resany=</code><kbd>hexmask</kbd><code> | resall=</code><kbd>hexmask</kbd><code>]</code><dd>Obtain and print traffic counts collected and maintained by
1256the monitor facility.
1257With the exception of <code>sort=</code><kbd>sortorder</kbd>,
1258the options filter the list returned by <code>ntpd</code>.
1259The <code>limited</code> and <code>kod</code> options return only entries
1260representing client addresses from which the last packet received
1261triggered either discarding or a KoD response.
1262The <code>mincount=</code><kbd>count</kbd> option filters entries representing
1263less than <kbd>count</kbd> packets.
1264The <code>laddr=</code><kbd>localaddr</kbd> option filters entries for packets
1265received on any local address other than <kbd>localaddr</kbd>.
1266<code>resany=</code><kbd>hexmask</kbd> and <code>resall=</code><kbd>hexmask</kbd>
1267filter entries containing none or less than all, respectively,
1268of the bits in <kbd>hexmask</kbd>, which must begin with <code>0x</code>.
1269<br>
1270The <kbd>sortorder</kbd> defaults to <code>lstint</code> and may be any of
1271<code>addr</code>, <code>count</code>, <code>avgint</code>, <code>lstint</code>, or
1272any of those preceded by a minus sign (hyphen) to reverse the sort order.
1273The output columns are:
1274
1275     <p><table summary=""><tr align="left"><th valign="top" width="10%">Column </th><th valign="top" width="40%">Description
1276
1277     <p><br></th></tr><tr align="left"><td valign="top" width="10%"><code>lstint</code>
1278</td><td valign="top" width="40%">
1279Interval in s between the receipt of the most recent packet from this
1280address and the completion of the retrieval of the MRU list by <code>ntpq</code>
1281
1282     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>avgint</code>
1283</td><td valign="top" width="40%">
1284Average interval in s between packets from this address.
1285
1286     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>rstr</code>
1287</td><td valign="top" width="40%">
1288Restriction flags associated with this address.
1289Most are copied unchanged from the matching <code>restrict</code> command,
1290however 0x400 (kod) and 0x20 (limited) flags are cleared unless
1291the last packet from this address triggered a rate control response.
1292
1293     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>r</code>
1294</td><td valign="top" width="40%">
1295Rate control indicator, either a period, <code>L</code> or <code>K</code> for
1296no rate control response, rate limiting by discarding, or
1297rate limiting with a KoD response, respectively.
1298
1299     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>m</code>
1300</td><td valign="top" width="40%">
1301Packet mode.
1302<br></td></tr><tr align="left"><td valign="top" width="10%"><code>v</code>
1303</td><td valign="top" width="40%">
1304Packet version number.
1305
1306     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>count</code>
1307</td><td valign="top" width="40%">
1308Packets received from this address.
1309
1310     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>rport</code>
1311</td><td valign="top" width="40%">
1312Source port of last packet from this address.
1313
1314     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>remote address</code>
1315</td><td valign="top" width="40%">
1316DNS name, numeric address, or address followed by claimed DNS name which
1317could not be verified in parentheses.
1318
1319     <br></td></tr></table>
1320
1321     <br><dt><code><a name="mreadvar"></a> mreadvar </code><kbd>assocID</kbd> <kbd>assocID</kbd><code> [ </code><kbd>variable_name</kbd><code> [ = </code><kbd>value</kbd><code>[ ... ]</code><dt><code><a name="mrv"></a> mrv </code><kbd>assocID</kbd> <kbd>assocID</kbd><code> [ </code><kbd>variable_name</kbd><code> [ = </code><kbd>value</kbd><code>[ ... ]</code><dd>Perform the same function as the <code>readvar</code> command,
1322except for a range of association IDs.
1323This range is determined from the association list cached by
1324the most recent <code>associations</code> command.
1325
1326     <br><dt><code><a name="passoc"></a> passociations</code><dd>Perform the same function as the <code>associations command</code>, except that
1327it uses previously stored data rather than making a new query.
1328
1329     <br><dt><code><a name="pe"></a> peers</code><dd>Display a list of peers in the form:
1330<br>
1331<code>[tally]remote refid st t when pool reach delay offset jitter</code>
1332
1333     <p><table summary=""><tr align="left"><th valign="top" width="10%">Variable </th><th valign="top" width="20%">Description
1334<br></th></tr><tr align="left"><td valign="top" width="10%"><code>[tally]</code>
1335</td><td valign="top" width="20%">
1336single-character code indicating current value of the <code>select</code> field
1337of the <a href="decode.html#peer">peer status word</a>.
1338
1339     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>remote</code>
1340</td><td valign="top" width="20%">
1341host name (or IP number) of peer
1342
1343     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>refid</code>
1344</td><td valign="top" width="20%">
1345association ID or <a href="decode.html#kiss">kiss code</a>.
1346
1347     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>st</code>
1348</td><td valign="top" width="20%">
1349stratum
1350
1351     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>t</code>
1352</td><td valign="top" width="20%">
1353<code>u</code>: unicast or manycast client,
1354<code>b</code>: broadcast or multicast client,
1355<code>l</code>: local (reference clock),
1356<code>s</code>: symmetric (peer),
1357<code>A</code>: manycast server,
1358<code>B</code>: broadcast server,
1359<code>M</code>: multicast server.
1360
1361     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>when</code>
1362</td><td valign="top" width="20%">
1363sec/min/hr since last received packet
1364
1365     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>poll</code>
1366</td><td valign="top" width="20%">
1367poll interval (log(2) s)
1368
1369     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>reach</code>
1370</td><td valign="top" width="20%">
1371reach shift register (octal)
1372
1373     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>delay</code>
1374</td><td valign="top" width="20%">
1375roundtrip delay
1376
1377     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>offset</code>
1378</td><td valign="top" width="20%">
1379offset of server relative to this host
1380
1381     <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>jitter</code>
1382</td><td valign="top" width="20%">
1383jitter
1384
1385     <br></td></tr></table>
1386
1387     <br><dt><code><a name="rv"></a> readvar </code><kbd>assocID</kbd> <kbd>name</kbd><code> [ = </code><kbd>value</kbd><code> ] [,...]</code><dt><code>rv </code><kbd>assocID</kbd><code> [ </code><kbd>name</kbd><code> ] [,...]</code><dd>Display the specified variables.
1388If <kbd>assocID</kbd> is zero,
1389the variables are from the <a href="#system">system variables</a> name space,
1390otherwise they are from the <a href="#peer">peer variables</a> name space.
1391The <kbd>assocID</kbd> is required, as the same name can occur in both spaces.
1392If no <kbd>name</kbd> is included,
1393all operative variables in the name space are displayed.
1394In this case only, if the <kbd>assocID</kbd> is omitted, it is assumed zero.
1395Multiple names are specified with comma separators and without whitespace.
1396Note that time values are represented in milliseconds and
1397frequency values in parts-per-million (PPM).
1398Some NTP timestamps are represented in the format YYYYMMDDTTTT,
1399where YYYY is the year, MM the month of year, DD the day of month and
1400TTTT the time of day.
1401
1402     <br><dt><code><a name="saveconfig"></a> saveconfig </code><kbd>filename</kbd><dd>Write the current configuration, including any runtime modifications
1403given with <code>:config</code> or <code>config-from-file</code>,
1404to the ntpd host's file <kbd>filename</kbd>.
1405This command will be rejected by the server unless
1406<a href="miscopt.html#saveconfigdir">saveconfigdir</a>
1407appears in the <code>ntpd</code> configuration file.
1408<kbd>filename</kbd> can use <code>strftime()</code> format specifiers
1409to substitute the current date and time, for example,
1410<code>saveconfig ntp-%Y%m%d-%H%M%S.conf</code>.
1411The filename used is stored in system variable <code>savedconfig</code>.
1412Authentication is required.
1413
1414     <br><dt><code><a name="writevar"></a> writevar </code><kbd>assocID</kbd> <kbd>name</kbd><code> = </code><kbd>value</kbd><code> [,...]</code><dd>Write the specified variables.
1415If the <kbd>assocID</kbd> is zero, the variables are from the
1416<a href="#system">system variables</a> name space, otherwise they are from the
1417<a href="#peer">peer variables</a> name	space.
1418The <kbd>assocID</kbd> is required,
1419as the same name can occur in both spaces.
1420
1421     <br><dt><code><a name="sysinfo"></a> sysinfo</code><dd>Display operational summary.
1422
1423     <br><dt><code><a name="sysstats"></a> sysstats</code><dd>Print statistics counters maintained in the protocol module.
1424
1425  </dl>
1426
1427<div class="node">
1428<p><hr>
1429<a name="Status-Words-and-Kiss-Codes"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#System-Variables">System Variables</a>,
1430Previous:&nbsp;<a rel="previous" accesskey="p" href="#Control-Message-Commands">Control Message Commands</a>,
1431Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1432<br>
1433</div>
1434
1435<!-- node-name,  next,  previous,  up -->
1436<h3 class="section">Status Words and Kiss Codes</h3>
1437
1438<p>The current state of the operating program is shown
1439in a set of status words maintained by the system
1440and each association separately.
1441These words are displayed in the <code>rv</code> and <code>as</code> commands
1442both in hexadecimal and decoded short tip strings.
1443The codes, tips and short explanations are on the
1444<a href="decode.html">Event Messages and Status Words</a> page.
1445The page also includes a list of system and peer messages,
1446the code for the latest of which is included in the status word.
1447
1448  <p>Information resulting from protocol machine state transitions
1449is displayed using an informal set of ASCII strings called
1450<a href="decode.html#kiss">kiss codes</a>.
1451The original purpose was for kiss-o'-death (KoD) packets sent
1452by the server to advise the client of an unusual condition.
1453They are now displayed, when appropriate,
1454in the reference identifier field in various billboards.
1455
1456<div class="node">
1457<p><hr>
1458<a name="System-Variables"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Peer-Variables">Peer Variables</a>,
1459Previous:&nbsp;<a rel="previous" accesskey="p" href="#Status-Words-and-Kiss-Codes">Status Words and Kiss Codes</a>,
1460Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1461<br>
1462</div>
1463
1464<!-- node-name,  next,  previous,  up -->
1465<h3 class="section">System Variables</h3>
1466
1467<p>The following system variables appear in the <code>rv</code> billboard.
1468Not all variables are displayed in some configurations.
1469
1470  <p><table summary=""><tr align="left"><th valign="top" width="10%">Variable </th><th valign="top" width="20%">Description
1471
1472<p><br></th></tr><tr align="left"><td valign="top" width="10%"><code>status</code>
1473</td><td valign="top" width="20%">
1474<a href="decode.html#sys">system status word</a>
1475
1476<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>version</code>
1477</td><td valign="top" width="20%">
1478NTP software version and build time
1479
1480<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>processor</code>
1481</td><td valign="top" width="20%">
1482hardware platform and version
1483
1484<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>system</code>
1485</td><td valign="top" width="20%">
1486operating system and version
1487
1488<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>leap</code>
1489</td><td valign="top" width="20%">
1490leap warning indicator (0-3)
1491
1492<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>stratum</code>
1493</td><td valign="top" width="20%">
1494stratum (1-15)
1495
1496<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>precision</code>
1497</td><td valign="top" width="20%">
1498precision (log(2) s)
1499
1500<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>rootdelay</code>
1501</td><td valign="top" width="20%">
1502total roundtrip delay to the primary reference clock
1503
1504<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>rootdisp</code>
1505</td><td valign="top" width="20%">
1506total dispersion to the primary reference clock
1507
1508<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>peer</code>
1509</td><td valign="top" width="20%">
1510system peer association ID
1511
1512<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>tc</code>
1513time constant and poll exponent (log(2) s) (3-17)
1514
1515  <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>mintc</code>
1516minimum time constant (log(2) s) (3-10)
1517
1518  <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>clock</code>
1519</td><td valign="top" width="20%">
1520date and time of day
1521
1522<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>refid</code>
1523reference ID or <a href="decode.html#kiss">kiss code</a>
1524
1525  <p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>reftime</code>
1526</td><td valign="top" width="20%">
1527reference time
1528
1529<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>offset</code>
1530</td><td valign="top" width="20%">
1531combined offset of server relative to this host
1532
1533<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>sys_jitter</code>
1534</td><td valign="top" width="20%">
1535combined system jitter
1536
1537<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>frequency</code>
1538</td><td valign="top" width="20%">
1539frequency offset (PPM) relative to hardware clock
1540
1541<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>clk_wander</code>
1542</td><td valign="top" width="20%">
1543clock frequency wander (PPM)
1544
1545<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>clk_jitter</code>
1546</td><td valign="top" width="20%">
1547clock jitter
1548
1549<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>tai</code>
1550</td><td valign="top" width="20%">
1551TAI-UTC offset (s)
1552
1553<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>leapsec</code>
1554</td><td valign="top" width="20%">
1555NTP seconds when the next leap second is/was inserted
1556
1557<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>expire</code>
1558</td><td valign="top" width="20%">
1559NTP seconds when the NIST leapseconds file expires
1560
1561  <br></td></tr></table>
1562
1563  <p>The jitter and wander statistics are exponentially-weighted RMS averages.
1564The system jitter is defined in the NTPv4 specification;
1565the clock jitter statistic is computed by the clock discipline module.
1566
1567  <p>When the NTPv4 daemon is compiled with the OpenSSL software library,
1568additional system variables are displayed, including some or all of the
1569following, depending on the particular Autokey dance:
1570
1571  <p><table summary=""><tr align="left"><th valign="top" width="10%">Variable </th><th valign="top" width="20%">Description
1572
1573<p><br></th></tr><tr align="left"><td valign="top" width="10%"><code>host</code>
1574</td><td valign="top" width="20%">
1575Autokey host name for this host
1576
1577<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>ident</code>
1578</td><td valign="top" width="20%">
1579Autokey group name for this host
1580
1581<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>flags</code>
1582</td><td valign="top" width="20%">
1583host flags  (see Autokey specification)
1584
1585<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>digest</code>
1586</td><td valign="top" width="20%">
1587OpenSSL message digest algorithm
1588
1589<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>signature</code>
1590</td><td valign="top" width="20%">
1591OpenSSL digest/signature scheme
1592
1593<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>update</code>
1594</td><td valign="top" width="20%">
1595NTP seconds at last signature update
1596
1597<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>cert</code>
1598</td><td valign="top" width="20%">
1599certificate subject, issuer and certificate flags
1600
1601<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>until</code>
1602</td><td valign="top" width="20%">
1603NTP seconds when the certificate expires
1604
1605  <br></td></tr></table>
1606
1607<div class="node">
1608<p><hr>
1609<a name="Peer-Variables"></a>Next:&nbsp;<a rel="next" accesskey="n" href="#Clock-Variables">Clock Variables</a>,
1610Previous:&nbsp;<a rel="previous" accesskey="p" href="#System-Variables">System Variables</a>,
1611Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1612<br>
1613</div>
1614
1615<!-- node-name,  next,  previous,  up -->
1616<h3 class="section">Peer Variables</h3>
1617
1618<p>The following peer variables appear in the <code>rv</code> billboard
1619for each association.
1620Not all variables are displayed in some configurations.
1621
1622  <p><table summary=""><tr align="left"><th valign="top" width="10%">Variable </th><th valign="top" width="20%">Description
1623
1624<p><br></th></tr><tr align="left"><td valign="top" width="10%"><code>associd</code>
1625</td><td valign="top" width="20%">
1626association ID
1627
1628<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>status</code>
1629</td><td valign="top" width="20%">
1630<a href="decode.html#peer">peer status word</a>
1631
1632<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>srcadr</code>
1633<br></td></tr><tr align="left"><td valign="top" width="10%"><code>srcport</code>
1634</td><td valign="top" width="20%">
1635source (remote) IP address and port
1636
1637<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>dstadr</code>
1638<br></td></tr><tr align="left"><td valign="top" width="10%"><code>dstport</code>
1639</td><td valign="top" width="20%">
1640destination (local) IP address and port
1641
1642<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>leap</code>
1643</td><td valign="top" width="20%">
1644leap indicator (0-3)
1645
1646<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>stratum</code>
1647</td><td valign="top" width="20%">
1648stratum (0-15)
1649
1650<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>precision</code>
1651</td><td valign="top" width="20%">
1652precision (log(2) s)
1653
1654<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>rootdelay</code>
1655</td><td valign="top" width="20%">
1656total roundtrip delay to the primary reference clock
1657
1658<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>rootdisp</code>
1659</td><td valign="top" width="20%">total root dispersion to the primary reference clock
1660
1661<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>refid</code>
1662</td><td valign="top" width="20%">
1663reference ID or <a href="decode.html#kiss">kiss code</a>
1664
1665<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>reftime</code>
1666</td><td valign="top" width="20%">
1667reference time
1668
1669<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>reach</code>
1670</td><td valign="top" width="20%">
1671reach register (octal)
1672
1673<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>unreach</code>
1674</td><td valign="top" width="20%">
1675unreach counter
1676
1677<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>hmode</code>
1678</td><td valign="top" width="20%">
1679host mode (1-6)
1680
1681<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>pmode</code>
1682</td><td valign="top" width="20%">
1683peer mode (1-5)
1684
1685<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>hpoll</code>
1686</td><td valign="top" width="20%">
1687host poll exponent (log(2) s) (3-17)
1688<br></td></tr><tr align="left"><td valign="top" width="10%"><code>ppoll</code>
1689</td><td valign="top" width="20%">
1690peer poll exponent (log(2) s) (3-17)
1691
1692<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>headway</code>
1693</td><td valign="top" width="20%">
1694headway (see <a href="rate.html">Rate Management and the Kiss-o'-Death Packet</a>)
1695
1696<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>flash</code>
1697</td><td valign="top" width="20%">
1698<a href="decode.html#flash">flash status word</a>
1699
1700<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>offset</code>
1701</td><td valign="top" width="20%">
1702filter offset
1703
1704<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>delay</code>
1705</td><td valign="top" width="20%">
1706filter delay
1707
1708<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>dispersion</code>
1709</td><td valign="top" width="20%">
1710filter dispersion
1711
1712<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>jitter</code>
1713</td><td valign="top" width="20%">
1714filter jitter
1715
1716<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>ident</code>
1717</td><td valign="top" width="20%">
1718Autokey group name for this association
1719
1720<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>bias</code>
1721</td><td valign="top" width="20%">
1722unicast/broadcast bias
1723
1724<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>xleave</code>
1725</td><td valign="top" width="20%">
1726interleave delay (see <a href="xleave.html">NTP Interleaved Modes</a>)
1727
1728  <br></td></tr></table>
1729
1730  <p>The bias variable is calculated when the first broadcast packet is received
1731after the calibration volley.  It represents the offset of the broadcast
1732subgraph relative to the unicast subgraph.  The xleave variable appears
1733only the interleaved symmetric and interleaved modes.  It represents
1734the internal queuing, buffering and transmission delays for the preceding
1735packet.
1736
1737  <p>When the NTPv4 daemon is compiled with the OpenSSL software library,
1738additional peer variables are displayed, including the following:
1739
1740  <p><table summary=""><tr align="left"><th valign="top" width="10%">Variable </th><th valign="top" width="20%">Description
1741
1742<p><br></th></tr><tr align="left"><td valign="top" width="10%"><code>flags</code>
1743</td><td valign="top" width="20%">
1744peer flags (see Autokey specification)
1745
1746<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>host</code>
1747</td><td valign="top" width="20%">
1748Autokey server name
1749
1750<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>flags</code>
1751</td><td valign="top" width="20%">
1752peer flags (see Autokey specification)
1753
1754<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>signature</code>
1755</td><td valign="top" width="20%">
1756OpenSSL digest/signature scheme
1757
1758<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>initsequence</code>
1759</td><td valign="top" width="20%">
1760initial key ID
1761
1762<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>initkey</code>
1763</td><td valign="top" width="20%">
1764initial key index
1765
1766<p><br></td></tr><tr align="left"><td valign="top" width="10%"><code>timestamp</code>
1767</td><td valign="top" width="20%">
1768Autokey signature timestamp
1769
1770  <br></td></tr></table>
1771
1772<div class="node">
1773<p><hr>
1774<a name="Clock-Variables"></a>Previous:&nbsp;<a rel="previous" accesskey="p" href="#Peer-Variables">Peer Variables</a>,
1775Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1776<br>
1777</div>
1778
1779<!-- node-name,  next,  previous,  up -->
1780<h3 class="section">Clock Variables</h3>
1781
1782<p>The following clock variables appear in the <code>cv</code> billboard for each association with a reference clock.  Not all variables are displayed in some configurations.
1783
1784  <p><table summary=""><tr align="left"><th valign="top" width="10%">Variable </th><th valign="top" width="20%">Description
1785<br></th></tr><tr align="left"><td valign="top" width="10%"><code>associd</code>
1786</td><td valign="top" width="20%">association ID
1787<br></td></tr><tr align="left"><td valign="top" width="10%"><code>status</code>
1788</td><td valign="top" width="20%"><a href="decode.html#clock">clock status word</a>
1789<br></td></tr><tr align="left"><td valign="top" width="10%"><code>device</code>
1790</td><td valign="top" width="20%">device description
1791<br></td></tr><tr align="left"><td valign="top" width="10%"><code>timecode</code>
1792</td><td valign="top" width="20%">ASCII time code string (specific to device)
1793<br></td></tr><tr align="left"><td valign="top" width="10%"><code>poll</code>
1794</td><td valign="top" width="20%">poll messages sent
1795<br></td></tr><tr align="left"><td valign="top" width="10%"><code>noreply</code>
1796</td><td valign="top" width="20%">no reply
1797<br></td></tr><tr align="left"><td valign="top" width="10%"><code>badformat</code>
1798</td><td valign="top" width="20%">bad format
1799<br></td></tr><tr align="left"><td valign="top" width="10%"><code>baddata</code>
1800</td><td valign="top" width="20%">bad date or time
1801<br></td></tr><tr align="left"><td valign="top" width="10%"><code>fudgetime1</code>
1802</td><td valign="top" width="20%">fudge time 1
1803<br></td></tr><tr align="left"><td valign="top" width="10%"><code>fudgetime2</code>
1804</td><td valign="top" width="20%">fudge time 2
1805<br></td></tr><tr align="left"><td valign="top" width="10%"><code>stratum</code>
1806</td><td valign="top" width="20%">driver stratum
1807<br></td></tr><tr align="left"><td valign="top" width="10%"><code>refid</code>
1808</td><td valign="top" width="20%">driver reference ID
1809<br></td></tr><tr align="left"><td valign="top" width="10%"><code>flags</code>
1810</td><td valign="top" width="20%">driver flags
1811  <br></td></tr></table>
1812
1813</body></html>
1814
1815