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