xref: /freebsd/contrib/ntp/ntpq/invoke-ntpq.texi (revision 63d1fd5970ec814904aa0f4580b10a0d302d08b2)
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>...&lt;...&gt;...</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