diff options
Diffstat (limited to 'ntpq/invoke-ntpq.texi')
| -rw-r--r-- | ntpq/invoke-ntpq.texi | 1086 |
1 files changed, 1086 insertions, 0 deletions
diff --git a/ntpq/invoke-ntpq.texi b/ntpq/invoke-ntpq.texi new file mode 100644 index 0000000..e30ccd1 --- /dev/null +++ b/ntpq/invoke-ntpq.texi @@ -0,0 +1,1086 @@ +@node ntpq Invocation +@section Invoking ntpq +@pindex ntpq +@cindex standard NTP query program +@ignore +# +# EDIT THIS FILE WITH CAUTION (invoke-ntpq.texi) +# +# It has been AutoGen-ed December 2, 2014 at 08:58:08 AM by AutoGen 5.18.5pre4 +# From the definitions ntpq-opts.def +# and the template file agtexi-cmd.tpl +@end ignore + + +The +@code{ntpq} +utility program is used to query NTP servers which +implement the standard NTP mode 6 control message formats defined +in Appendix B of the NTPv3 specification RFC1305, requesting +information about current state and/or changes in that state. +The same formats are used in NTPv4, although some of the +variables have changed and new ones added. The description on this +page is for the NTPv4 variables. +The program may 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} +utility can also obtain and print a +list of peers in a common format by sending multiple queries to the +server. + +If one or more request options is included on the command line +when +@code{ntpq} +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} +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. +The +@code{ntpq} +utility will prompt for +commands if the standard input is a terminal device. + +@code{ntpq} +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. +The +@code{ntpq} +utility makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. + +Specifying a +command line option other than +@code{-i} +or +@code{-n} +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +@code{ntpq} +will attempt to read +interactive format commands from the standard input. +@subsubsection Internal Commands +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. + +A +number of interactive format commands are executed entirely within +the +@code{ntpq} +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +@table @asis +@item @code{?} @code{[@kbd{command_keyword}]} +@item @code{help} @code{[@kbd{command_keyword}]} +A +@quoteleft{}?@quoteright{} +by itself will print a list of all the command +keywords known to this incarnation of +@code{ntpq} +A +@quoteleft{}?@quoteright{} +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +@code{ntpq} +than this manual +page. +@item @code{addvars} @kbd{variable_name}@code{[@code{=value}]} @code{...} +@item @code{rmvars} @kbd{variable_name} @code{...} +@item @code{clearvars} +@item @code{showvars} +The data carried by NTP mode 6 messages consists of a list of +items of the form +@quoteleft{}variable_name=value@quoteright{}, +where the +@quoteleft{}=value@quoteright{} +is ignored, and can be omitted, +in requests to the server to read variables. +The +@code{ntpq} +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +@code{readlist} +and +@code{writelist} +commands described below. +The +@code{addvars} +command allows variables and their optional values to be added to +the list. +If more than one variable is to be added, the list should +be comma-separated and not contain white space. +The +@code{rmvars} +command can be used to remove individual variables from the list, +while the +@code{clearlist} +command removes all variables from the +list. +The +@code{showvars} +command displays the current list of optional variables. +@item @code{authenticate} @code{[yes | no]} +Normally +@code{ntpq} +does not authenticate requests unless +they are write requests. +The command +@quoteleft{}authenticate yes@quoteright{} +causes +@code{ntpq} +to send authentication with all requests it +makes. +Authenticated requests causes some servers to handle +requests slightly differently, and can occasionally melt the CPU in +fuzzballs if you turn authentication on before doing a +@code{peer} +display. +The command +@quoteleft{}authenticate@quoteright{} +causes +@code{ntpq} +to display whether or not +@code{ntpq} +is currently autheinticating requests. +@item @code{cooked} +Causes output from query commands to be "cooked", so that +variables which are recognized by +@code{ntpq} +will have their +values reformatted for human consumption. +Variables which +@code{ntpq} +thinks should have a decodable value but didn't are +marked with a trailing +@quoteleft{}?@quoteright{}. +@item @code{debug} @code{[@code{more} | @code{less} | @code{off}]} +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. +@item @code{delay} @kbd{milliseconds} +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. +@item @code{exit} +Exit +@code{ntpq} +@item @code{host} @kbd{hostname} +Set the host to which future queries will be sent. +@kbd{hostname} +may be either a host name or a numeric address. +@item @code{hostnames} @code{[@code{yes} | @code{no}]} +If +@code{yes} +is specified, host names are printed in +information displays. +If +@code{no} +is specified, numeric +addresses are printed instead. +The default is +@code{yes}, +unless +modified using the command line +@code{-n} +switch. +@item @code{keyid} @kbd{keyid} +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +@item @code{keytype} @code{[@code{md5} | @code{OpenSSLDigestType}]} +Specify the type of key to use for authenticating requests. +@code{md5} +is alway supported. +If +@code{ntpq} +was built with OpenSSL support, +any digest type supported by OpenSSL can also be provided. +If no argument is given, the current +@code{keytype} +is displayed. +@item @code{ntpversion} @code{[@code{1} | @code{2} | @code{3} | @code{4}]} +Sets the NTP version number which +@code{ntpq} +claims in +packets. +Defaults to 3, and note that mode 6 control messages (and +modes, for that matter) didn't exist in NTP version 1. +There appear +to be no servers left which demand version 1. +With no argument, displays the current NTP version that will be used +when communicating with servers. +@item @code{passwd} +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +@code{poll} +@kbd{n} +@code{verbose} +@item @code{quit} +Exit +@code{ntpq} +@item @code{raw} +Causes all output from query commands is printed as received +from the remote server. +The only formating/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form. +@item @code{timeout} @kbd{milliseconds} +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +@code{ntpq} +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +@item @code{version} +Print the version of the +@code{ntpq} +program. +@end table + +@subsubsection Control Message Commands +Association IDs are used to identify system, peer and clock variables. +System variables are assigned an association ID of zero and system name space, while each association is assigned a nonzero association ID and peer namespace. +Most control commands send a single mode-6 message to the server and expect a single response message. +The exceptions are the +@code{peers} +command, which sends a series of messages, +and the +@code{mreadlist} +and +@code{mreadvar} +commands, which iterate over a range of associations. +@table @asis +@item @code{associations} +Display a list of mobilized associations in the form: +@example +ind assid status conf reach auth condition last_event cnt +@end example +@table @asis +@item Sy String Ta Sy Description +@item @code{ind} @code{Ta} @code{index} @code{on} @code{this} @code{list} +@item @code{assid} @code{Ta} @code{association} @code{ID} +@item @code{status} @code{Ta} @code{peer} @code{status} @code{word} +@item @code{conf} @code{Ta} @code{yes}: @code{persistent,} @code{no}: @code{ephemeral} +@item @code{reach} @code{Ta} @code{yes}: @code{reachable,} @code{no}: @code{unreachable} +@item @code{auth} @code{Ta} @code{ok}, @code{yes}, @code{bad} @code{and} @code{none} +@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)} +@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)} +@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)} +@end table +@item @code{authinfo} +Display the authentication statistics. +@item @code{clockvar} @kbd{assocID} @code{[@kbd{name}@code{[@code{=}@kbd{value}]}]} @code{[...]} +@item @code{cv} @kbd{assocID} @code{[@kbd{name}@code{[@code{=}@kbd{value}]}]} @code{[...]} +Display a list of clock variables for those associations supporting a reference clock. +@item @code{:config} @code{[...]} +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. +@item @code{config-from-file} @kbd{filename} +Send the each line of +@kbd{filename} +to 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. +@item @code{ifstats} +Display statistics for each local network address. Authentication is required. +@item @code{iostats} +Display network and reference clock I/O statistics. +@item @code{kerninfo} +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. +@item @code{lassociations} +Perform the same function as the associations command, except display mobilized and unmobilized associations. +@item @code{lopeers} @code{[@code{-4} | @code{-6}]} +Obtain and print a list of all peers and clients showing +@kbd{dstadr} +(associated with any given IP version). +@item @code{lpeers} @code{[@code{-4} | @code{-6}]} +Print a peer spreadsheet for the appropriate IP version(s). +@kbd{dstadr} +(associated with any given IP version). +@item @code{monstats} +Display monitor facility statistics. +@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}]} +Obtain and print traffic counts collected and maintained by the monitor facility. +With the exception of +@code{sort}=@kbd{sortorder}, +the options filter the list returned by +@code{ntpd.} +The +@code{limited} +and +@code{kod} +options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response. +The +@code{mincount}=@kbd{count} +option filters entries representing less than +@kbd{count} +packets. +The +@code{laddr}=@kbd{localaddr} +option filters entries for packets received on any local address other than +@kbd{localaddr}. +@code{resany}=@kbd{hexmask} +and +@code{resall}=@kbd{hexmask} +filter entries containing none or less than all, respectively, of the bits in +@kbd{hexmask}, +which must begin with +@code{0x}. +The +@kbd{sortorder} +defaults to +@code{lstint} +and may be any of +@code{addr}, +@code{count}, +@code{avgint}, +@code{lstint}, +or any of those preceded by a minus sign (hyphen) to reverse the sort order. +The output columns are: +@table @asis +@item Column +Description +@item @code{lstint} +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 +@code{ntpq} +@item @code{avgint} +Average interval in s between packets from this address. +@item @code{rstr} +Restriction flags associated with this address. +Most are copied unchanged from the matching +@code{restrict} +command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response. +@item @code{r} +Rate control indicator, either +a period, +@code{L} +or +@code{K} +for no rate control response, +rate limiting by discarding, or rate limiting with a KoD response, respectively. +@item @code{m} +Packet mode. +@item @code{v} +Packet version number. +@item @code{count} +Packets received from this address. +@item @code{rport} +Source port of last packet from this address. +@item @code{remote} @code{address} +DNS name, numeric address, or address followed by +claimed DNS name which could not be verified in parentheses. +@end table +@item @code{mreadvar} @code{assocID} @code{assocID} @code{[@kbd{variable_name}@code{[=@kbd{value}]} ...]} +@item @code{mrv} @code{assocID} @code{assocID} @code{[@kbd{variable_name}@code{[=@kbd{value}]} ...]} +Perform the same function as the +@code{readvar} +command, except for a range of association IDs. +This range is determined from the association list cached by the most recent +@code{associations} +command. +@item @code{opeers} @code{[@code{-4} | @code{-6}]} +Obtain and print the old-style list of all peers and clients showing +@kbd{dstadr} +(associated with any given IP version), +rather than the +@kbd{refid}. +@item @code{passociations} +Perform the same function as the +@code{associations} +command, +except that it uses previously stored data rather than making a new query. +@item @code{peers} +Display a list of peers in the form: +@example +[tally]remote refid st t when pool reach delay offset jitter +@end example +@table @asis +@item Variable +Description +@item @code{[tally]} +single-character code indicating current value of the +@code{select} +field of the +.Lk decode.html#peer "peer status word" +@item @code{remote} +host name (or IP number) of peer. +The value displayed will be truncated to 15 characters unless the +@code{-w} +flag is given, in which case the full value will be displayed +on the first line, +and the remaining data is displayed on the next line. +@item @code{refid} +association ID or +.Lk decode.html#kiss "'kiss code" +@item @code{st} +stratum +@item @code{t} +@code{u}: +unicast or manycast client, +@code{b}: +broadcast or multicast client, +@code{l}: +local (reference clock), +@code{s}: +symmetric (peer), +@code{A}: +manycast server, +@code{B}: +broadcast server, +@code{M}: +multicast server +@item @code{when} +sec/min/hr since last received packet +@item @code{poll} +poll interval (log2 s) +@item @code{reach} +reach shift register (octal) +@item @code{delay} +roundtrip delay +@item @code{offset} +offset of server relative to this host +@item @code{jitter} +jitter +@end table +@item @code{pstats} @kbd{assocID} +Show the statistics for the peer with the given +@kbd{assocID}. +@item @code{readlist} @kbd{assocID} +@item @code{rl} @kbd{assocID} +Read the system or peer variables included in the variable list. +@item @code{readvar} @kbd{assocID} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]} +@item @code{rv} @kbd{assocID} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]} +Display the specified variables. +If +@kbd{assocID} +is zero, the variables are from the +@ref{System Variables} +name space, otherwise they are from the +@ref{Peer Variables} +name space. +The +@kbd{assocID} +is required, as the same name can occur in both spaces. +If no +@kbd{name} +is included, all operative variables in the name space are displayed. + +In this case only, if the +@kbd{assocID} +is omitted, it is assumed zero. +Multiple names are specified with comma separators and without whitespace. +Note that time values are represented in milliseconds +and frequency values in parts-per-million (PPM). +Some NTP timestamps are represented in the format +YYYYMMDDTTTT , +where YYYY is the year, +MM the month of year, +DD the day of month and +TTTT the time of day. +@item @code{reslist} +Show the access control (restrict) list for +@code{ntpq} + +@item @code{saveconfig} @kbd{filename} +Write the current configuration, +including any runtime modifications given with +@code{:config} +or +@code{config-from-file}, +to the ntpd host's file +@kbd{filename}. +This command will be rejected by the server unless +.Lk miscopt.html#saveconfigdir "saveconfigdir" +appears in the +@code{ntpd} +configuration file. +@kbd{filename} +can use +@code{strftime()} +format specifies to substitute the current date and time, for example, +@code{q]saveconfig} @code{ntp-%Y%m%d-%H%M%S.confq]}. +The filename used is stored in system variable +@code{savedconfig}. +Authentication is required. +@item @code{timerstats} +Display interval timer counters. +@item @code{writelist} @kbd{assocID} +Write the system or peer variables included in the variable list. +@item @code{writevar} @kbd{assocID} @kbd{name}=@kbd{value} @code{[, ...]} +Write the specified variables. +If the +@kbd{assocID} +is zero, the variables are from the +@ref{System Variables} +name space, otherwise they are from the +@ref{Peer Variables} +name space. +The +@kbd{assocID} +is required, as the same name can occur in both spaces. +@item @code{sysinfo} +Display operational summary. +@item @code{sysstats} +Print statistics counters maintained in the protocol module. +@end table + +@subsubsection Status Words and Kiss Codes + +The current state of the operating program is shown +in a set of status words +maintained by the system. +Status information is also available on a per-association basis. +These words are displayed in the +@code{rv} +and +@code{as} +commands both in hexadecimal and in decoded short tip strings. +The codes, tips and short explanations are documented on the +.Lk decode.html "Event Messages and Status Words" +page. +The page also includes a list of system and peer messages, +the code for the latest of which is included in the status word. + +Information resulting from protocol machine state transitions +is displayed using an informal set of ASCII strings called +.Lk decode.html#kiss "kiss codes" . +The original purpose was for kiss-o'-death (KoD) packets +sent by the server to advise the client of an unusual condition. +They are now displayed, when appropriate, +in the reference identifier field in various billboards. + +@subsubsection System Variables +The following system variables appear in the +@code{rv} +billboard. +Not all variables are displayed in some configurations. +@table @asis +@item Variable +Description +@item @code{status} +.Lk decode.html#sys "system status word" +@item @code{version} +NTP software version and build time +@item @code{processor} +hardware platform and version +@item @code{system} +operating system and version +@item @code{leap} +leap warning indicator (0-3) +@item @code{stratum} +stratum (1-15) +@item @code{precision} +precision (log2 s) +@item @code{rootdelay} +total roundtrip delay to the primary reference clock +@item @code{rootdisp} +total dispersion to the primary reference clock +@item @code{peer} +system peer association ID +@item @code{tc} +time constant and poll exponent (log2 s) (3-17) +@item @code{mintc} +minimum time constant (log2 s) (3-10) +@item @code{clock} +date and time of day +@item @code{refid} +reference ID or +.Lk decode.html#kiss "kiss code" +@item @code{reftime} +reference time +@item @code{offset} +combined offset of server relative to this host +@item @code{sys_jitter} +combined system jitter +@item @code{frequency} +frequency offset (PPM) relative to hardware clock +@item @code{clk_wander} +clock frequency wander (PPM) +@item @code{clk_jitter} +clock jitter +@item @code{tai} +TAI-UTC offset (s) +@item @code{leapsec} +NTP seconds when the next leap second is/was inserted +@item @code{expire} +NTP seconds when the NIST leapseconds file expires +@end table +The jitter and wander statistics are exponentially-weighted RMS averages. +The system jitter is defined in the NTPv4 specification; +the clock jitter statistic is computed by the clock discipline module. + +When the NTPv4 daemon is compiled with the OpenSSL software library, +additional system variables are displayed, +including some or all of the following, +depending on the particular Autokey dance: + +@table @asis +@item Variable +Description +@item @code{host} +Autokey host name for this host +@item @code{ident} +Autokey group name for this host +@item @code{flags} +host flags (see Autokey specification) +@item @code{digest} +OpenSSL message digest algorithm +@item @code{signature} +OpenSSL digest/signature scheme +@item @code{update} +NTP seconds at last signature update +@item @code{cert} +certificate subject, issuer and certificate flags +@item @code{until} +NTP seconds when the certificate expires +@end table +@subsubsection Peer Variables +The following peer variables appear in the +@code{rv} +billboard for each association. +Not all variables are displayed in some configurations. + +@table @asis +@item Variable +Description +@item @code{associd} +association ID +@item @code{status} +.Lk decode.html#peer "peer status word" +@item @code{srcadr} +source (remote) IP address +@item @code{srcport} +source (remote) port +@item @code{dstadr} +destination (local) IP address +@item @code{dstport} +destination (local) port +@item @code{leap} +leap indicator (0-3) +@item @code{stratum} +stratum (0-15) +@item @code{precision} +precision (log2 s) +@item @code{rootdelay} +total roundtrip delay to the primary reference clock +@item @code{rootdisp} +total root dispersion to the primary reference clock +@item @code{refid} +reference ID or +.Lk decode.html#kiss "kiss code" +@item @code{reftime} +reference time +@item @code{reach} +reach register (octal) +@item @code{unreach} +unreach counter +@item @code{hmode} +host mode (1-6) +@item @code{pmode} +peer mode (1-5) +@item @code{hpoll} +host poll exponent (log2 s) (3-17) +@item @code{ppoll} +peer poll exponent (log2 s) (3-17) +@item @code{headway} +headway (see +.Lk rate.html "Rate Management and the Kiss-o'-Death Packet" ) +@item @code{flash} +.Lk decode.html#flash "flash status word" +@item @code{offset} +filter offset +@item @code{delay} +filter delay +@item @code{dispersion} +filter dispersion +@item @code{jitter} +filter jitter +@item @code{ident} +Autokey group name for this association +@item @code{bias} +unicast/broadcast bias +@item @code{xleave} +interleave delay (see +.Lk xleave.html "NTP Interleaved Modes" ) +@end table +The +@code{bias} +variable is calculated when the first broadcast packet is received +after the calibration volley. +It represents the offset of the broadcast subgraph relative to the unicast subgraph. +The +@code{xleave} +variable appears only for the interleaved symmetric and interleaved modes. +It represents the internal queuing, buffering and transmission delays +for the preceding packet. + +When the NTPv4 daemon is compiled with the OpenSSL software library, +additional peer variables are displayed, including the following: +@table @asis +@item Variable +Description +@item @code{flags} +peer flags (see Autokey specification) +@item @code{host} +Autokey server name +@item @code{flags} +peer flags (see Autokey specification) +@item @code{signature} +OpenSSL digest/signature scheme +@item @code{initsequence} +initial key ID +@item @code{initkey} +initial key index +@item @code{timestamp} +Autokey signature timestamp +@end table + +@subsubsection Clock Variables +The following clock variables appear in the +@code{cv} +billboard for each association with a reference clock. +Not all variables are displayed in some configurations. +@table @asis +@item Variable +Description +@item @code{associd} +association ID +@item @code{status} +.Lk decode.html#clock "clock status word" +@item @code{device} +device description +@item @code{timecode} +ASCII time code string (specific to device) +@item @code{poll} +poll messages sent +@item @code{noreply} +no reply +@item @code{badformat} +bad format +@item @code{baddata} +bad date or time +@item @code{fudgetime1} +fudge time 1 +@item @code{fudgetime2} +fudge time 2 +@item @code{stratum} +driver stratum +@item @code{refid} +driver reference ID +@item @code{flags} +driver flags +@end table + +This section was generated by @strong{AutoGen}, +using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpq} program. +This software is released under the NTP license, <http://ntp.org/license>. + +@menu +* ntpq usage:: ntpq help/usage (@option{--help}) +* ntpq ipv4:: ipv4 option (-4) +* ntpq ipv6:: ipv6 option (-6) +* ntpq command:: command option (-c) +* ntpq interactive:: interactive option (-i) +* ntpq numeric:: numeric option (-n) +* ntpq old-rv:: old-rv option +* ntpq peers:: peers option (-p) +* ntpq wide:: wide option (-w) +* ntpq config:: presetting/configuring ntpq +* ntpq exit status:: exit status +@end menu + +@node ntpq usage +@subsection ntpq help/usage (@option{--help}) +@cindex ntpq help + +This is the automatically generated usage text for ntpq. + +The text printed is the same whether selected with the @code{help} option +(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print +the usage text by passing it through a pager program. +@code{more-help} is disabled on platforms without a working +@code{fork(2)} function. The @code{PAGER} environment variable is +used to select the program, defaulting to @file{more}. Both will exit +with a status code of 0. + +@exampleindent 0 +@example +ntpq - standard NTP query program - Ver. 4.2.7p482 +Usage: ntpq [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ host ...] + Flg Arg Option-Name Description + -4 no ipv4 Force IPv4 DNS name resolution + - prohibits the option 'ipv6' + -6 no ipv6 Force IPv6 DNS name resolution + - prohibits the option 'ipv4' + -c Str command run a command and exit + - may appear multiple times + -d no debug-level Increase debug verbosity level + - may appear multiple times + -D Num set-debug-level Set the debug verbosity level + - may appear multiple times + -i no interactive Force ntpq to operate in interactive mode + - prohibits these options: + command + peers + -n no numeric numeric host addresses + no old-rv Always output status line with readvar + -p no peers Print a list of the peers + - prohibits the option 'interactive' + -w no wide Display the full 'remote' value + opt version output version information and exit + -? no help display extended usage information and exit + -! no more-help extended usage information passed thru pager + -> opt save-opts save the option state to a config file + -< Str load-opts load options from a config file + - disabled as '--no-load-opts' + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +The following option preset mechanisms are supported: + - reading file $HOME/.ntprc + - reading file ./.ntprc + - examining environment variables named NTPQ_* + +Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org> +@end example +@exampleindent 4 + +@node ntpq ipv4 +@subsection ipv4 option (-4) +@cindex ntpq-ipv4 + +This is the ``force ipv4 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv6. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +@node ntpq ipv6 +@subsection ipv6 option (-6) +@cindex ntpq-ipv6 + +This is the ``force ipv6 dns name resolution'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +ipv4. +@end itemize + +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +@node ntpq command +@subsection command option (-c) +@cindex ntpq-command + +This is the ``run a command and exit'' option. +This option takes a string argument @file{cmd}. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +may appear an unlimited number of times. +@end itemize + +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +@node ntpq interactive +@subsection interactive option (-i) +@cindex ntpq-interactive + +This is the ``force ntpq to operate in interactive mode'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +command, peers. +@end itemize + +Force @code{ntpq} to operate in interactive mode. +Prompts will be written to the standard output and +commands read from the standard input. +@node ntpq numeric +@subsection numeric option (-n) +@cindex ntpq-numeric + +This is the ``numeric host addresses'' option. +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +@node ntpq old-rv +@subsection old-rv option +@cindex ntpq-old-rv + +This is the ``always output status line with readvar'' option. +By default, @code{ntpq} now suppresses the @code{associd=...} +line that precedes the output of @code{readvar} +(alias @code{rv}) when a single variable is requested, such as +@code{ntpq -c "rv 0 offset"}. +This option causes @code{ntpq} to include both lines of output +for a single-variable @code{readvar}. +Using an environment variable to +preset this option in a script will enable both older and +newer @code{ntpq} to behave identically in this regard. +@node ntpq peers +@subsection peers option (-p) +@cindex ntpq-peers + +This is the ``print a list of the peers'' option. + +@noindent +This option has some usage constraints. It: +@itemize @bullet +@item +must not appear in combination with any of the following options: +interactive. +@end itemize + +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'peers' interactive command. +@node ntpq wide +@subsection wide option (-w) +@cindex ntpq-wide + +This is the ``display the full 'remote' value'' option. +Display the full value of the 'remote' value. If this requires +more than 15 characters, display the full value, emit a newline, +and continue the data display properly indented on the next line. + + +@node ntpq config +@subsection presetting/configuring ntpq + +Any option that is not marked as @i{not presettable} may be preset by +loading 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 +the options listed above in upper case and segmented with underscores. +The @code{NTPQ} variable will be tokenized and parsed like +the command line. The remaining variables are tested for existence and their +values are treated like option arguments. + + +@noindent +@code{libopts} will search in 2 places for configuration files: +@itemize @bullet +@item +$HOME +@item +$PWD +@end itemize +The environment variables @code{HOME}, and @code{PWD} +are expanded and replaced when @file{ntpq} runs. +For any of these that are plain files, they are simply processed. +For any that are directories, then a file named @file{.ntprc} is searched for +within that directory and processed. + +Configuration files may be in a wide variety of formats. +The basic format is an option name followed by a value (argument) on the +same line. Values may be separated from the option name with a colon, +equal sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + +Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: +@example +[NTPQ] +@end example +@noindent +or by +@example +<?program ntpq> +@end example +@noindent +Do not mix these styles within one configuration file. + +Compound values and carefully constructed string values may also be +specified using XML syntax: +@example +<option-name> + <sub-opt>...<...>...</sub-opt> +</option-name> +@end example +@noindent +yielding an @code{option-name.sub-opt} string value of +@example +"...<...>..." +@end example +@code{AutoOpts} does not track suboptions. You simply note that it is a +hierarchicly valued option. @code{AutoOpts} does provide a means for searching +the associated name/value pair list (see: optionFindValue). + +The command line options relating to configuration and/or usage help are: + +@subsubheading version (-) + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much licensing +detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. +Only the first letter of the argument is examined: + +@table @samp +@item version +Only print the version. This is the default. +@item copyright +Name the copyright usage licensing terms. +@item verbose +Print the full copyright usage licensing terms. +@end table + +@node ntpq exit status +@subsection ntpq exit status + +One of the following exit values will be returned: +@table @samp +@item 0 (EXIT_SUCCESS) +Successful program execution. +@item 1 (EXIT_FAILURE) +The operation failed or the command syntax was not valid. +@item 66 (EX_NOINPUT) +A specified configuration file could not be loaded. +@item 70 (EX_SOFTWARE) +libopts had an internal operational error. Please report +it to autogen-users@@lists.sourceforge.net. Thank you. +@end table |