invoke-ntpq.texi revision 330106
1@node ntpq Invocation 2@section Invoking ntpq 3@pindex ntpq 4@cindex standard NTP query program 5@ignore 6# 7# EDIT THIS FILE WITH CAUTION (invoke-ntpq.texi) 8# 9# It has been AutoGen-ed February 27, 2018 at 05:15:26 PM by AutoGen 5.18.5 10# From the definitions ntpq-opts.def 11# and the template file agtexi-cmd.tpl 12@end ignore 13 14 15The 16@code{ntpq} 17utility program is used to query NTP servers to monitor NTP operations 18and performance, requesting 19information about current state and/or changes in that state. 20The program may be run either in interactive mode or controlled using 21command line arguments. 22Requests to read and write arbitrary 23variables can be assembled, with raw and pretty-printed output 24options being available. 25The 26@code{ntpq} 27utility can also obtain and print a 28list of peers in a common format by sending multiple queries to the 29server. 30 31If one or more request options is included on the command line 32when 33@code{ntpq} 34is executed, each of the requests will be sent 35to the NTP servers running on each of the hosts given as command 36line arguments, or on localhost by default. 37If no request options 38are given, 39@code{ntpq} 40will attempt to read commands from the 41standard input and execute these on the NTP server running on the 42first host given on the command line, again defaulting to localhost 43when no other host is specified. 44The 45@code{ntpq} 46utility will prompt for 47commands if the standard input is a terminal device. 48 49@code{ntpq} 50uses NTP mode 6 packets to communicate with the 51NTP server, and hence can be used to query any compatible server on 52the network which permits it. 53Note that since NTP is a UDP protocol 54this communication will be somewhat unreliable, especially over 55large distances in terms of network topology. 56The 57@code{ntpq} 58utility makes 59one attempt to retransmit requests, and will time requests out if 60the remote host is not heard from within a suitable timeout 61time. 62 63Note that in contexts where a host name is expected, a 64@code{-4} 65qualifier preceding the host name forces resolution to the IPv4 66namespace, while a 67@code{-6} 68qualifier forces resolution to the IPv6 namespace. 69For examples and usage, see the 70@quotedblleft{}NTP Debugging Techniques@quotedblright{} 71page. 72 73Specifying a 74command line option other than 75@code{-i} 76or 77@code{-n} 78will 79cause the specified query (queries) to be sent to the indicated 80host(s) immediately. 81Otherwise, 82@code{ntpq} 83will attempt to read 84interactive format commands from the standard input. 85 86@subsubsection Internal Commands 87 88Interactive format commands consist of a keyword followed by zero 89to four arguments. 90Only enough characters of the full keyword to 91uniquely identify the command need be typed. 92 93A 94number of interactive format commands are executed entirely within 95the 96@code{ntpq} 97utility itself and do not result in NTP 98requests being sent to a server. 99These are described following. 100@table @asis 101@item @code{?} @code{[@kbd{command}]} 102@item @code{help} @code{[@kbd{command}]} 103A 104@quoteleft{}?@quoteright{} 105by itself will print a list of all the commands 106known to 107@code{ntpq} 108A 109@quoteleft{}?@quoteright{} 110followed by a command name will print function and usage 111information about the command. 112@item @code{addvars} @kbd{name}@code{[=@kbd{value}]}@code{[,...]} 113@item @code{rmvars} @kbd{name}@code{[,...]} 114@item @code{clearvars} 115@item @code{showvars} 116The arguments to this command consist of a list of 117items of the form 118@kbd{name}@code{[=@kbd{value}]}, 119where the 120.No = Ns Ar value 121is ignored, and can be omitted, 122in requests to the server to read variables. 123The 124@code{ntpq} 125utility maintains an internal list in which data to be included in 126messages can be assembled, and displayed or set using the 127@code{readlist} 128and 129@code{writelist} 130commands described below. 131The 132@code{addvars} 133command allows variables and their optional values to be added to 134the list. 135If more than one variable is to be added, the list should 136be comma-separated and not contain white space. 137The 138@code{rmvars} 139command can be used to remove individual variables from the list, 140while the 141@code{clearvars} 142command removes all variables from the 143list. 144The 145@code{showvars} 146command displays the current list of optional variables. 147@item @code{authenticate} @code{[@code{yes}|@code{no}]} 148Normally 149@code{ntpq} 150does not authenticate requests unless 151they are write requests. 152The command 153@code{authenticate} @code{yes} 154causes 155@code{ntpq} 156to send authentication with all requests it 157makes. 158Authenticated requests causes some servers to handle 159requests slightly differently. 160The command 161@code{authenticate} 162causes 163@code{ntpq} 164to display whether or not 165it is currently authenticating requests. 166@item @code{cooked} 167Causes output from query commands to be "cooked", so that 168variables which are recognized by 169@code{ntpq} 170will have their 171values reformatted for human consumption. 172Variables which 173@code{ntpq} 174could not decode completely are 175marked with a trailing 176@quoteleft{}?@quoteright{}. 177@item @code{debug} @code{[@code{more}|@code{less}|@code{off}]} 178With no argument, displays the current debug level. 179Otherwise, the debugging level is changed as indicated. 180@item @code{delay} @code{[@kbd{milliseconds}]} 181Specify a time interval to be added to timestamps included in 182requests which require authentication. 183This is used to enable 184(unreliable) server reconfiguration over long delay network paths 185or between machines whose clocks are unsynchronized. 186Actually the 187server does not now require timestamps in authenticated requests, 188so this command may be obsolete. 189Without any arguments, displays the current delay. 190@item @code{drefid} @code{[@code{hash}|@code{ipv4}]} 191Display refids as IPv4 or hash. 192Without any arguments, displays whether refids are shown as IPv4 193addresses or hashes. 194@item @code{exit} 195Exit 196@code{ntpq} 197@item @code{host} @code{[@kbd{name}]} 198Set the host to which future queries will be sent. 199The 200@kbd{name} 201may be either a host name or a numeric address. 202Without any arguments, displays the current host. 203@item @code{hostnames} @code{[@code{yes}|@code{no}]} 204If 205@code{yes} 206is specified, host names are printed in 207information displays. 208If 209@code{no} 210is specified, numeric 211addresses are printed instead. 212The default is 213@code{yes}, 214unless 215modified using the command line 216@code{-n} 217switch. 218Without any arguments, displays whether host names or numeric addresses 219are shown. 220@item @code{keyid} @code{[@kbd{keyid}]} 221This command allows the specification of a key number to be 222used to authenticate configuration requests. 223This must correspond 224to the 225@code{controlkey} 226key number the server has been configured to use for this 227purpose. 228Without any arguments, displays the current 229@kbd{keyid}. 230@item @code{keytype} @code{[@kbd{digest}]} 231Specify the digest algorithm to use for authenticating requests, with default 232@code{MD5}. 233If 234@code{ntpq} 235was built with OpenSSL support, and OpenSSL is installed, 236@kbd{digest} 237can be any message digest algorithm supported by OpenSSL. 238If no argument is given, the current 239@code{keytype} @kbd{digest} 240algorithm used is displayed. 241@item @code{ntpversion} @code{[@code{1}|@code{2}|@code{3}|@code{4}]} 242Sets the NTP version number which 243@code{ntpq} 244claims in 245packets. 246Defaults to 3, and note that mode 6 control messages (and 247modes, for that matter) didn't exist in NTP version 1. 248There appear 249to be no servers left which demand version 1. 250With no argument, displays the current NTP version that will be used 251when communicating with servers. 252@item @code{passwd} 253This command prompts you to type in a password (which will not 254be echoed) which will be used to authenticate configuration 255requests. 256The password must correspond to the key configured for 257use by the NTP server for this purpose if such requests are to be 258successful. 259@item @code{poll} @code{[@kbd{n}]} @code{[@code{verbose}]} 260Poll an NTP server in client mode 261@kbd{n} 262times. 263Poll not implemented yet. 264@item @code{quit} 265Exit 266@code{ntpq} 267@item @code{raw} 268Causes all output from query commands is printed as received 269from the remote server. 270The only formating/interpretation done on 271the data is to transform nonascii data into a printable (but barely 272understandable) form. 273@item @code{timeout} @code{[@kbd{milliseconds}]} 274Specify a timeout period for responses to server queries. 275The 276default is about 5000 milliseconds. 277Without any arguments, displays the current timeout period. 278Note that since 279@code{ntpq} 280retries each query once after a timeout, the total waiting time for 281a timeout will be twice the timeout value set. 282@item @code{version} 283Display the version of the 284@code{ntpq} 285program. 286@end table 287 288@subsubsection Control Message Commands 289Association ids are used to identify system, peer and clock variables. 290System variables are assigned an association id of zero and system name 291space, while each association is assigned a nonzero association id and 292peer namespace. 293Most control commands send a single message to the server and expect a 294single response message. 295The exceptions are the 296@code{peers} 297command, which sends a series of messages, 298and the 299@code{mreadlist} 300and 301@code{mreadvar} 302commands, which iterate over a range of associations. 303@table @asis 304@item @code{apeers} 305Display a list of peers in the form: 306@example 307[tally]remote refid assid st t when pool reach delay offset jitter 308@end example 309where the output is just like the 310@code{peers} 311command except that the 312@code{refid} 313is displayed in hex format and the association number is also displayed. 314@item @code{associations} 315Display a list of mobilized associations in the form: 316@example 317ind assid status conf reach auth condition last_event cnt 318@end example 319@table @asis 320@item Sy Variable Ta Sy Description 321@item @code{ind} @code{Ta} @code{index} @code{on} @code{this} @code{list} 322@item @code{assid} @code{Ta} @code{association} @code{id} 323@item @code{status} @code{Ta} @code{peer} @code{status} @code{word} 324@item @code{conf} @code{Ta} @code{yes}: @code{No} @code{persistent,} @code{no}: @code{No} @code{ephemeral} 325@item @code{reach} @code{Ta} @code{yes}: @code{No} @code{reachable,} @code{no}: @code{No} @code{unreachable} 326@item @code{auth} @code{Ta} @code{ok}, @code{yes}, @code{bad} @code{No} @code{and} @code{none} 327@item @code{condition} @code{Ta} @code{selection} @code{status} @code{(see} @code{the} @code{select} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)} 328@item @code{last_event} @code{Ta} @code{event} @code{report} @code{(see} @code{the} @code{event} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)} 329@item @code{cnt} @code{Ta} @code{event} @code{count} @code{(see} @code{the} @code{count} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)} 330@end table 331@item @code{authinfo} 332Display the authentication statistics counters: 333time since reset, stored keys, free keys, key lookups, keys not found, 334uncached keys, expired keys, encryptions, decryptions. 335@item @code{clocklist} @code{[@kbd{associd}]} 336@item @code{cl} @code{[@kbd{associd}]} 337Display all clock variables in the variable list for those associations 338supporting a reference clock. 339@item @code{clockvar} @code{[@kbd{associd}]} @code{[@kbd{name}@code{[=@kbd{value}]}]}@code{[,...]} 340@item @code{cv} @code{[@kbd{associd}]} @code{[@kbd{name}@code{[=@kbd{value}]}]}@code{[,...]} 341Display a list of clock variables for those associations supporting a 342reference clock. 343@item @code{:config} @kbd{configuration command line} 344Send the remainder of the command line, including whitespace, to the 345server as a run-time configuration command in the same format as a line 346in the configuration file. 347This command is experimental until further notice and clarification. 348Authentication is of course required. 349@item @code{config-from-file} @kbd{filename} 350Send each line of 351@kbd{filename} 352to the server as run-time configuration commands in the same format as 353lines in the configuration file. 354This command is experimental until further notice and clarification. 355Authentication is required. 356@item @code{ifstats} 357Display status and statistics counters for each local network interface address: 358interface number, interface name and address or broadcast, drop, flag, 359ttl, mc, received, sent, send failed, peers, uptime. 360Authentication is required. 361@item @code{iostats} 362Display network and reference clock I/O statistics: 363time since reset, receive buffers, free receive buffers, used receive buffers, 364low water refills, dropped packets, ignored packets, received packets, 365packets sent, packet send failures, input wakeups, useful input wakeups. 366@item @code{kerninfo} 367Display kernel loop and PPS statistics: 368associd, status, pll offset, pll frequency, maximum error, 369estimated error, kernel status, pll time constant, precision, 370frequency tolerance, pps frequency, pps stability, pps jitter, 371calibration interval, calibration cycles, jitter exceeded, 372stability exceeded, calibration errors. 373As with other ntpq output, times are in milliseconds; very small values 374may be shown as exponentials. 375The precision value displayed is in milliseconds as well, unlike the 376precision system variable. 377@item @code{lassociations} 378Perform the same function as the associations command, except display 379mobilized and unmobilized associations, including all clients. 380@item @code{lopeers} @code{[@code{-4}|@code{-6}]} 381Display a list of all peers and clients showing 382@code{dstadr} 383(associated with the given IP version). 384@item @code{lpassociations} 385Display the last obtained list of associations, including all clients. 386@item @code{lpeers} @code{[@code{-4}|@code{-6}]} 387Display a list of all peers and clients (associated with the given IP version). 388@item @code{monstats} 389Display monitor facility status, statistics, and limits: 390enabled, addresses, peak addresses, maximum addresses, 391reclaim above count, reclaim older than, kilobytes, maximum kilobytes. 392@item @code{mreadlist} @kbd{associdlo} @kbd{associdhi} 393@item @code{mrl} @kbd{associdlo} @kbd{associdhi} 394Perform the same function as the 395@code{readlist} 396command for a range of association ids. 397@item @code{mreadvar} @kbd{associdlo} @kbd{associdhi} @code{[@kbd{name}]}@code{[,...]} 398This range may be determined from the list displayed by any 399command showing associations. 400@item @code{mrv} @kbd{associdlo} @kbd{associdhi} @code{[@kbd{name}]}@code{[,...]} 401Perform the same function as the 402@code{readvar} 403command for a range of association ids. 404This range may be determined from the list displayed by any 405command showing associations. 406@item @code{mrulist} @code{[@code{limited} | @code{kod} | @code{mincount}=@kbd{count} | @code{laddr}=@kbd{localaddr} | @code{sort}=@code{[-]}@kbd{sortorder} | @code{resany}=@kbd{hexmask} | @code{resall}=@kbd{hexmask}]} 407Display traffic counts of the most recently seen source addresses 408collected and maintained by the monitor facility. 409With the exception of 410@code{sort}=@code{[-]}@kbd{sortorder}, 411the options filter the list returned by 412@code{ntpd(8)}. 413The 414@code{limited} 415and 416@code{kod} 417options return only entries representing client addresses from which the 418last packet received triggered either discarding or a KoD response. 419The 420@code{mincount}=@kbd{count} 421option filters entries representing less than 422@kbd{count} 423packets. 424The 425@code{laddr}=@kbd{localaddr} 426option filters entries for packets received on any local address other than 427@kbd{localaddr}. 428@code{resany}=@kbd{hexmask} 429and 430@code{resall}=@kbd{hexmask} 431filter entries containing none or less than all, respectively, of the bits in 432@kbd{hexmask}, 433which must begin with 434@code{0x}. 435The 436@kbd{sortorder} 437defaults to 438@code{lstint} 439and may be 440@code{addr}, 441@code{avgint}, 442@code{count}, 443@code{lstint}, 444or any of those preceded by 445@quoteleft{}-@quoteright{} 446to reverse the sort order. 447The output columns are: 448@table @asis 449@item Column 450Description 451@item @code{lstint} 452Interval in seconds between the receipt of the most recent packet from 453this address and the completion of the retrieval of the MRU list by 454@code{ntpq} 455@item @code{avgint} 456Average interval in s between packets from this address. 457@item @code{rstr} 458Restriction flags associated with this address. 459Most are copied unchanged from the matching 460@code{restrict} 461command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless 462the last packet from this address triggered a rate control response. 463@item @code{r} 464Rate control indicator, either 465a period, 466@code{L} 467or 468@code{K} 469for no rate control response, 470rate limiting by discarding, or rate limiting with a KoD response, respectively. 471@item @code{m} 472Packet mode. 473@item @code{v} 474Packet version number. 475@item @code{count} 476Packets received from this address. 477@item @code{rport} 478Source port of last packet from this address. 479@item @code{remote} @code{address} 480host or DNS name, numeric address, or address followed by 481claimed DNS name which could not be verified in parentheses. 482@end table 483@item @code{opeers} @code{[@code{-4} | @code{-6}]} 484Obtain and print the old-style list of all peers and clients showing 485@code{dstadr} 486(associated with the given IP version), 487rather than the 488@code{refid}. 489@item @code{passociations} 490Perform the same function as the 491@code{associations} 492command, 493except that it uses previously stored data rather than making a new query. 494@item @code{peers} 495Display a list of peers in the form: 496@example 497[tally]remote refid st t when pool reach delay offset jitter 498@end example 499@table @asis 500@item Variable 501Description 502@item @code{[tally]} 503single-character code indicating current value of the 504@code{select} 505field of the 506.Lk decode.html#peer "peer status word" 507@item @code{remote} 508host name (or IP number) of peer. 509The value displayed will be truncated to 15 characters unless the 510@code{ntpq} 511@code{-w} 512option is given, in which case the full value will be displayed 513on the first line, and if too long, 514the remaining data will be displayed on the next line. 515@item @code{refid} 516source IP address or 517.Lk decode.html#kiss "'kiss code" 518@item @code{st} 519stratum: 0 for local reference clocks, 1 for servers with local 520reference clocks, ..., 16 for unsynchronized server clocks 521@item @code{t} 522@code{u}: 523unicast or manycast client, 524@code{b}: 525broadcast or multicast client, 526@code{p}: 527pool source, 528@code{l}: 529local (reference clock), 530@code{s}: 531symmetric (peer), 532@code{A}: 533manycast server, 534@code{B}: 535broadcast server, 536@code{M}: 537multicast server 538@item @code{when} 539time in seconds, minutes, hours, or days since the last packet 540was received, or 541@quoteleft{}-@quoteright{} 542if a packet has never been received 543@item @code{poll} 544poll interval (s) 545@item @code{reach} 546reach shift register (octal) 547@item @code{delay} 548roundtrip delay 549@item @code{offset} 550offset of server relative to this host 551@item @code{jitter} 552offset RMS error estimate. 553@end table 554@item @code{pstats} @kbd{associd} 555Display the statistics for the peer with the given 556@kbd{associd}: 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@item @code{readlist} @code{[@kbd{associd}]} 562@item @code{rl} @code{[@kbd{associd}]} 563Display all system or peer variables. 564If the 565@kbd{associd} 566is omitted, it is assumed to be zero. 567@item @code{readvar} @code{[@kbd{associd} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}]} 568@item @code{rv} @code{[@kbd{associd} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}]} 569Display the specified system or peer variables. 570If 571@kbd{associd} 572is zero, the variables are from the 573@ref{System Variables} 574name space, otherwise they are from the 575@ref{Peer Variables} 576name space. 577The 578@kbd{associd} 579is required, as the same name can occur in both spaces. 580If no 581@kbd{name} 582is included, all operative variables in the name space are displayed. 583In this case only, if the 584@kbd{associd} 585is omitted, it is assumed to be zero. 586Multiple names are specified with comma separators and without whitespace. 587Note that time values are represented in milliseconds 588and frequency values in parts-per-million (PPM). 589Some NTP timestamps are represented in the format 590@kbd{YYYY}@kbd{MM} @kbd{DD} @kbd{TTTT}, 591where 592@kbd{YYYY} 593is the year, 594@kbd{MM} 595the month of year, 596@kbd{DD} 597the day of month and 598@kbd{TTTT} 599the time of day. 600@item @code{reslist} 601Display the access control (restrict) list for 602@code{ntpq} 603Authentication is required. 604@item @code{saveconfig} @kbd{filename} 605Save the current configuration, 606including any runtime modifications made by 607@code{:config} 608or 609@code{config-from-file}, 610to the NTP server host file 611@kbd{filename}. 612This command will be rejected by the server unless 613.Lk miscopt.html#saveconfigdir "saveconfigdir" 614appears in the 615@code{ntpd(8)} 616configuration file. 617@kbd{filename} 618can use 619@code{date(1)} 620format specifiers to substitute the current date and time, for 621example, 622@example 623@code{saveconfig} @file{ntp-%Y%m%d-%H%M%S.conf}. 624@end example 625The filename used is stored in system variable 626@code{savedconfig}. 627Authentication is required. 628@item @code{sysinfo} 629Display system operational summary: 630associd, status, system peer, system peer mode, leap indicator, 631stratum, log2 precision, root delay, root dispersion, 632reference id, reference time, system jitter, clock jitter, 633clock wander, broadcast delay, symm. auth. delay. 634@item @code{sysstats} 635Display system uptime and packet counts maintained in the 636protocol module: 637uptime, sysstats reset, packets received, current version, 638older version, bad length or format, authentication failed, 639declined, restricted, rate limited, KoD responses, 640processed for time. 641@item @code{timerstats} 642Display interval timer counters: 643time since reset, timer overruns, calls to transmit. 644@item @code{writelist} @kbd{associd} 645Set all system or peer variables included in the variable list. 646@item @code{writevar} @kbd{associd} @kbd{name}=@kbd{value} @code{[, ...]} 647Set the specified variables in the variable list. 648If the 649@kbd{associd} 650is zero, the variables are from the 651@ref{System Variables} 652name space, otherwise they are from the 653@ref{Peer Variables} 654name space. 655The 656@kbd{associd} 657is required, as the same name can occur in both spaces. 658Authentication is required. 659@end table 660 661@subsubsection Status Words and Kiss Codes 662The current state of the operating program is shown 663in a set of status words 664maintained by the system. 665Status information is also available on a per-association basis. 666These words are displayed by the 667@code{readlist} 668and 669@code{associations} 670commands both in hexadecimal and in decoded short tip strings. 671The codes, tips and short explanations are documented on the 672.Lk decode.html "Event Messages and Status Words" 673page. 674The page also includes a list of system and peer messages, 675the code for the latest of which is included in the status word. 676 677Information resulting from protocol machine state transitions 678is displayed using an informal set of ASCII strings called 679.Lk decode.html#kiss "kiss codes" . 680The original purpose was for kiss-o'-death (KoD) packets 681sent by the server to advise the client of an unusual condition. 682They are now displayed, when appropriate, 683in the reference identifier field in various billboards. 684 685@subsubsection System Variables 686The following system variables appear in the 687@code{readlist} 688billboard. 689Not all variables are displayed in some configurations. 690 691@table @asis 692@item Variable 693Description 694@item @code{status} 695.Lk decode.html#sys "system status word" 696@item @code{version} 697NTP software version and build time 698@item @code{processor} 699hardware platform and version 700@item @code{system} 701operating system and version 702@item @code{leap} 703leap warning indicator (0-3) 704@item @code{stratum} 705stratum (1-15) 706@item @code{precision} 707precision (log2 s) 708@item @code{rootdelay} 709total roundtrip delay to the primary reference clock 710@item @code{rootdisp} 711total dispersion to the primary reference clock 712@item @code{refid} 713reference id or 714.Lk decode.html#kiss "kiss code" 715@item @code{reftime} 716reference time 717@item @code{clock} 718date and time of day 719@item @code{peer} 720system peer association id 721@item @code{tc} 722time constant and poll exponent (log2 s) (3-17) 723@item @code{mintc} 724minimum time constant (log2 s) (3-10) 725@item @code{offset} 726combined offset of server relative to this host 727@item @code{frequency} 728frequency drift (PPM) relative to hardware clock 729@item @code{sys_jitter} 730combined system jitter 731@item @code{clk_wander} 732clock frequency wander (PPM) 733@item @code{clk_jitter} 734clock jitter 735@item @code{tai} 736TAI-UTC offset (s) 737@item @code{leapsec} 738NTP seconds when the next leap second is/was inserted 739@item @code{expire} 740NTP seconds when the NIST leapseconds file expires 741@end table 742The jitter and wander statistics are exponentially-weighted RMS averages. 743The system jitter is defined in the NTPv4 specification; 744the clock jitter statistic is computed by the clock discipline module. 745 746When the NTPv4 daemon is compiled with the OpenSSL software library, 747additional system variables are displayed, 748including some or all of the following, 749depending on the particular Autokey dance: 750@table @asis 751@item Variable 752Description 753@item @code{host} 754Autokey host name for this host 755@item @code{ident} 756Autokey group name for this host 757@item @code{flags} 758host flags (see Autokey specification) 759@item @code{digest} 760OpenSSL message digest algorithm 761@item @code{signature} 762OpenSSL digest/signature scheme 763@item @code{update} 764NTP seconds at last signature update 765@item @code{cert} 766certificate subject, issuer and certificate flags 767@item @code{until} 768NTP seconds when the certificate expires 769@end table 770@subsubsection Peer Variables 771The following peer variables appear in the 772@code{readlist} 773billboard for each association. 774Not all variables are displayed in some configurations. 775 776@table @asis 777@item Variable 778Description 779@item @code{associd} 780association id 781@item @code{status} 782.Lk decode.html#peer "peer status word" 783@item @code{srcadr} 784source (remote) IP address 785@item @code{srcport} 786source (remote) port 787@item @code{dstadr} 788destination (local) IP address 789@item @code{dstport} 790destination (local) port 791@item @code{leap} 792leap indicator (0-3) 793@item @code{stratum} 794stratum (0-15) 795@item @code{precision} 796precision (log2 s) 797@item @code{rootdelay} 798total roundtrip delay to the primary reference clock 799@item @code{rootdisp} 800total root dispersion to the primary reference clock 801@item @code{refid} 802reference id or 803.Lk decode.html#kiss "kiss code" 804@item @code{reftime} 805reference time 806@item @code{rec} 807last packet received time 808@item @code{reach} 809reach register (octal) 810@item @code{unreach} 811unreach counter 812@item @code{hmode} 813host mode (1-6) 814@item @code{pmode} 815peer mode (1-5) 816@item @code{hpoll} 817host poll exponent (log2 s) (3-17) 818@item @code{ppoll} 819peer poll exponent (log2 s) (3-17) 820@item @code{headway} 821headway (see 822.Lk rate.html "Rate Management and the Kiss-o'-Death Packet" ) 823@item @code{flash} 824.Lk decode.html#flash "flash status word" 825@item @code{keyid} 826symmetric key id 827@item @code{offset} 828filter offset 829@item @code{delay} 830filter delay 831@item @code{dispersion} 832filter dispersion 833@item @code{jitter} 834filter jitter 835@item @code{bias} 836unicast/broadcast bias 837@item @code{xleave} 838interleave delay (see 839.Lk xleave.html "NTP Interleaved Modes" ) 840@end table 841The 842@code{bias} 843variable is calculated when the first broadcast packet is received 844after the calibration volley. 845It represents the offset of the broadcast subgraph relative to the 846unicast subgraph. 847The 848@code{xleave} 849variable appears only for the interleaved symmetric and interleaved modes. 850It represents the internal queuing, buffering and transmission delays 851for the preceding packet. 852 853When the NTPv4 daemon is compiled with the OpenSSL software library, 854additional peer variables are displayed, including the following: 855@table @asis 856@item Variable 857Description 858@item @code{flags} 859peer flags (see Autokey specification) 860@item @code{host} 861Autokey server name 862@item @code{flags} 863peer flags (see Autokey specification) 864@item @code{signature} 865OpenSSL digest/signature scheme 866@item @code{initsequence} 867initial key id 868@item @code{initkey} 869initial key index 870@item @code{timestamp} 871Autokey signature timestamp 872@item @code{ident} 873Autokey group name for this association 874@end table 875 876@subsubsection Clock Variables 877The following clock variables appear in the 878@code{clocklist} 879billboard for each association with a reference clock. 880Not all variables are displayed in some configurations. 881@table @asis 882@item Variable 883Description 884@item @code{associd} 885association id 886@item @code{status} 887.Lk decode.html#clock "clock status word" 888@item @code{device} 889device description 890@item @code{timecode} 891ASCII time code string (specific to device) 892@item @code{poll} 893poll messages sent 894@item @code{noreply} 895no reply 896@item @code{badformat} 897bad format 898@item @code{baddata} 899bad date or time 900@item @code{fudgetime1} 901fudge time 1 902@item @code{fudgetime2} 903fudge time 2 904@item @code{stratum} 905driver stratum 906@item @code{refid} 907driver reference id 908@item @code{flags} 909driver flags 910@end table 911 912This section was generated by @strong{AutoGen}, 913using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpq} program. 914This software is released under the NTP license, <http://ntp.org/license>. 915 916@menu 917* ntpq usage:: ntpq help/usage (@option{--help}) 918* ntpq ipv4:: ipv4 option (-4) 919* ntpq ipv6:: ipv6 option (-6) 920* ntpq command:: command option (-c) 921* ntpq interactive:: interactive option (-i) 922* ntpq numeric:: numeric option (-n) 923* ntpq old-rv:: old-rv option 924* ntpq peers:: peers option (-p) 925* ntpq refid:: refid option (-r) 926* ntpq wide:: wide option (-w) 927* ntpq config:: presetting/configuring ntpq 928* ntpq exit status:: exit status 929@end menu 930 931@node ntpq usage 932@subsection ntpq help/usage (@option{--help}) 933@cindex ntpq help 934 935This is the automatically generated usage text for ntpq. 936 937The text printed is the same whether selected with the @code{help} option 938(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print 939the usage text by passing it through a pager program. 940@code{more-help} is disabled on platforms without a working 941@code{fork(2)} function. The @code{PAGER} environment variable is 942used to select the program, defaulting to @file{more}. Both will exit 943with a status code of 0. 944 945@exampleindent 0 946@example 947ntpq - standard NTP query program - Ver. 4.2.8p11 948Usage: ntpq [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ host ...] 949 Flg Arg Option-Name Description 950 -4 no ipv4 Force IPv4 name resolution 951 - prohibits the option 'ipv6' 952 -6 no ipv6 Force IPv6 name resolution 953 - prohibits the option 'ipv4' 954 -c Str command run a command and exit 955 - may appear multiple times 956 -d no debug-level Increase debug verbosity level 957 - may appear multiple times 958 -D Num set-debug-level Set the debug verbosity level 959 - may appear multiple times 960 -i no interactive Force ntpq to operate in interactive mode 961 - prohibits these options: 962 command 963 peers 964 -n no numeric numeric host addresses 965 no old-rv Always output status line with readvar 966 -p no peers Print a list of the peers 967 - prohibits the option 'interactive' 968 -r KWd refid Set default display type for S2+ refids 969 -w no wide Display the full 'remote' value 970 opt version output version information and exit 971 -? no help display extended usage information and exit 972 -! no more-help extended usage information passed thru pager 973 -> opt save-opts save the option state to a config file 974 -< Str load-opts load options from a config file 975 - disabled as '--no-load-opts' 976 - may appear multiple times 977 978Options are specified by doubled hyphens and their name or by a single 979hyphen and the flag character. 980 981The following option preset mechanisms are supported: 982 - reading file $HOME/.ntprc 983 - reading file ./.ntprc 984 - examining environment variables named NTPQ_* 985 986The valid "refid" option keywords are: 987 hash ipv4 988 or an integer from 0 through 1 989 990Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org> 991@end example 992@exampleindent 4 993 994@node ntpq ipv4 995@subsection ipv4 option (-4) 996@cindex ntpq-ipv4 997 998This is the ``force ipv4 name resolution'' option. 999 1000@noindent 1001This option has some usage constraints. It: 1002@itemize @bullet 1003@item 1004must not appear in combination with any of the following options: 1005ipv6. 1006@end itemize 1007 1008Force resolution of following host names on the command line 1009to the IPv4 namespace. 1010@node ntpq ipv6 1011@subsection ipv6 option (-6) 1012@cindex ntpq-ipv6 1013 1014This is the ``force ipv6 name resolution'' option. 1015 1016@noindent 1017This option has some usage constraints. It: 1018@itemize @bullet 1019@item 1020must not appear in combination with any of the following options: 1021ipv4. 1022@end itemize 1023 1024Force resolution of following host names on the command line 1025to the IPv6 namespace. 1026@node ntpq command 1027@subsection command option (-c) 1028@cindex ntpq-command 1029 1030This is the ``run a command and exit'' option. 1031This option takes a string argument @file{cmd}. 1032 1033@noindent 1034This option has some usage constraints. It: 1035@itemize @bullet 1036@item 1037may appear an unlimited number of times. 1038@end itemize 1039 1040The following argument is interpreted as an interactive format command 1041and is added to the list of commands to be executed on the specified 1042host(s). 1043@node ntpq interactive 1044@subsection interactive option (-i) 1045@cindex ntpq-interactive 1046 1047This is the ``force ntpq to operate in interactive mode'' option. 1048 1049@noindent 1050This option has some usage constraints. It: 1051@itemize @bullet 1052@item 1053must not appear in combination with any of the following options: 1054command, peers. 1055@end itemize 1056 1057Force @code{ntpq} to operate in interactive mode. 1058Prompts will be written to the standard output and 1059commands read from the standard input. 1060@node ntpq numeric 1061@subsection numeric option (-n) 1062@cindex ntpq-numeric 1063 1064This is the ``numeric host addresses'' option. 1065Output all host addresses in dotted-quad numeric format rather than 1066converting to the canonical host names. 1067@node ntpq old-rv 1068@subsection old-rv option 1069@cindex ntpq-old-rv 1070 1071This is the ``always output status line with readvar'' option. 1072By default, @code{ntpq} now suppresses the @code{associd=...} 1073line that precedes the output of @code{readvar} 1074(alias @code{rv}) when a single variable is requested, such as 1075@code{ntpq -c "rv 0 offset"}. 1076This option causes @code{ntpq} to include both lines of output 1077for a single-variable @code{readvar}. 1078Using an environment variable to 1079preset this option in a script will enable both older and 1080newer @code{ntpq} to behave identically in this regard. 1081@node ntpq peers 1082@subsection peers option (-p) 1083@cindex ntpq-peers 1084 1085This is the ``print a list of the peers'' option. 1086 1087@noindent 1088This option has some usage constraints. It: 1089@itemize @bullet 1090@item 1091must not appear in combination with any of the following options: 1092interactive. 1093@end itemize 1094 1095Print a list of the peers known to the server as well as a summary 1096of their state. This is equivalent to the 'peers' interactive command. 1097@node ntpq refid 1098@subsection refid option (-r) 1099@cindex ntpq-refid 1100 1101This is the ``set default display type for s2+ refids'' option. 1102This option takes a keyword argument. 1103 1104@noindent 1105This option has some usage constraints. It: 1106@itemize @bullet 1107@item 1108This option takes a keyword as its argument. 1109The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_REFID). 1110The available keywords are: 1111@example 1112 hash ipv4 1113@end example 1114 1115or their numeric equivalent.@end itemize 1116 1117Set the default display format for S2+ refids. 1118@node ntpq wide 1119@subsection wide option (-w) 1120@cindex ntpq-wide 1121 1122This is the ``display the full 'remote' value'' option. 1123Display the full value of the 'remote' value. If this requires 1124more than 15 characters, display the full value, emit a newline, 1125and continue the data display properly indented on the next line. 1126 1127 1128@node ntpq config 1129@subsection presetting/configuring ntpq 1130 1131Any option that is not marked as @i{not presettable} may be preset by 1132loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTPQ} and @code{NTPQ_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of 1133the options listed above in upper case and segmented with underscores. 1134The @code{NTPQ} variable will be tokenized and parsed like 1135the command line. The remaining variables are tested for existence and their 1136values are treated like option arguments. 1137 1138 1139@noindent 1140@code{libopts} will search in 2 places for configuration files: 1141@itemize @bullet 1142@item 1143$HOME 1144@item 1145$PWD 1146@end itemize 1147The environment variables @code{HOME}, and @code{PWD} 1148are expanded and replaced when @file{ntpq} runs. 1149For any of these that are plain files, they are simply processed. 1150For any that are directories, then a file named @file{.ntprc} is searched for 1151within that directory and processed. 1152 1153Configuration files may be in a wide variety of formats. 1154The basic format is an option name followed by a value (argument) on the 1155same line. Values may be separated from the option name with a colon, 1156equal sign or simply white space. Values may be continued across multiple 1157lines by escaping the newline with a backslash. 1158 1159Multiple programs may also share the same initialization file. 1160Common options are collected at the top, followed by program specific 1161segments. The segments are separated by lines like: 1162@example 1163[NTPQ] 1164@end example 1165@noindent 1166or by 1167@example 1168<?program ntpq> 1169@end example 1170@noindent 1171Do not mix these styles within one configuration file. 1172 1173Compound values and carefully constructed string values may also be 1174specified using XML syntax: 1175@example 1176<option-name> 1177 <sub-opt>...<...>...</sub-opt> 1178</option-name> 1179@end example 1180@noindent 1181yielding an @code{option-name.sub-opt} string value of 1182@example 1183"...<...>..." 1184@end example 1185@code{AutoOpts} does not track suboptions. You simply note that it is a 1186hierarchicly valued option. @code{AutoOpts} does provide a means for searching 1187the associated name/value pair list (see: optionFindValue). 1188 1189The command line options relating to configuration and/or usage help are: 1190 1191@subsubheading version (-) 1192 1193Print the program version to standard out, optionally with licensing 1194information, then exit 0. The optional argument specifies how much licensing 1195detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. 1196Only the first letter of the argument is examined: 1197 1198@table @samp 1199@item version 1200Only print the version. This is the default. 1201@item copyright 1202Name the copyright usage licensing terms. 1203@item verbose 1204Print the full copyright usage licensing terms. 1205@end table 1206 1207@node ntpq exit status 1208@subsection ntpq exit status 1209 1210One of the following exit values will be returned: 1211@table @samp 1212@item 0 (EXIT_SUCCESS) 1213Successful program execution. 1214@item 1 (EXIT_FAILURE) 1215The operation failed or the command syntax was not valid. 1216@item 66 (EX_NOINPUT) 1217A specified configuration file could not be loaded. 1218@item 70 (EX_SOFTWARE) 1219libopts had an internal operational error. Please report 1220it to autogen-users@@lists.sourceforge.net. Thank you. 1221@end table 1222