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