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