1 /* -*- Mode: Text -*- */
3 autogen definitions options;
7 #include autogen-version.def
10 prog-title = "standard NTP query program";
11 argument = '[ host ...]';
17 descrip = "Force IPv4 DNS name resolution";
19 Force DNS resolution of following host names on the command line
20 to the IPv4 namespace.
28 descrip = "Force IPv6 DNS name resolution";
30 Force DNS resolution of following host names on the command line
31 to the IPv6 namespace.
39 descrip = "run a command and exit";
42 call-proc = ntpq_custom_opt_handler;
44 The following argument is interpreted as an interactive format command
45 and is added to the list of commands to be executed on the specified
50 #include debug-opt.def
55 flags-cant = command, peers;
56 descrip = "Force ntpq to operate in interactive mode";
58 Force @code{ntpq} to operate in interactive mode.
59 Prompts will be written to the standard output and
60 commands read from the standard input.
67 descrip = "numeric host addresses";
69 Output all host addresses in dotted-quad numeric format rather than
70 converting to the canonical host names.
76 descrip = "Always output status line with readvar";
78 By default, @code{ntpq} now suppresses the @code{associd=...}
79 line that precedes the output of @code{readvar}
80 (alias @code{rv}) when a single variable is requested, such as
81 @code{ntpq -c "rv 0 offset"}.
82 This option causes @code{ntpq} to include both lines of output
83 for a single-variable @code{readvar}.
84 Using an environment variable to
85 preset this option in a script will enable both older and
86 newer @code{ntpq} to behave identically in this regard.
93 descrip = "Print a list of the peers";
94 flags-cant = interactive;
95 call-proc = ntpq_custom_opt_handler;
97 Print a list of the peers known to the server as well as a summary
98 of their state. This is equivalent to the 'peers' interactive command.
105 descrip = "Set default display type for S2+ refids";
107 keyword = hash, ipv4;
110 Set the default display format for S2+ refids.
117 descrip = "Display the full 'remote' value";
119 Display the full value of the 'remote' value. If this requires
120 more than 15 characters, display the full value, emit a newline,
121 and continue the data display properly indented on the next line.
126 ds-type = 'DESCRIPTION';
128 ds-text = <<- _END_PROG_MDOC_DESCRIP
132 utility program is used to query NTP servers which
133 implement the standard NTP mode 6 control message formats defined
134 in Appendix B of the NTPv3 specification RFC1305, requesting
135 information about current state and/or changes in that state.
136 The same formats are used in NTPv4, although some of the
137 variables have changed and new ones added. The description on this
138 page is for the NTPv4 variables.
139 The program may be run either in interactive mode or controlled using
140 command line arguments.
141 Requests to read and write arbitrary
142 variables can be assembled, with raw and pretty-printed output
143 options being available.
146 utility can also obtain and print a
147 list of peers in a common format by sending multiple queries to the
150 If one or more request options is included on the command line
153 is executed, each of the requests will be sent
154 to the NTP servers running on each of the hosts given as command
155 line arguments, or on localhost by default.
156 If no request options
159 will attempt to read commands from the
160 standard input and execute these on the NTP server running on the
161 first host given on the command line, again defaulting to localhost
162 when no other host is specified.
165 utility will prompt for
166 commands if the standard input is a terminal device.
169 uses NTP mode 6 packets to communicate with the
170 NTP server, and hence can be used to query any compatible server on
171 the network which permits it.
172 Note that since NTP is a UDP protocol
173 this communication will be somewhat unreliable, especially over
174 large distances in terms of network topology.
178 one attempt to retransmit requests, and will time requests out if
179 the remote host is not heard from within a suitable timeout
183 command line option other than
188 cause the specified query (queries) to be sent to the indicated
193 interactive format commands from the standard input.
194 .Ss "Internal Commands"
195 Interactive format commands consist of a keyword followed by zero
197 Only enough characters of the full keyword to
198 uniquely identify the command need be typed.
201 number of interactive format commands are executed entirely within
204 utility itself and do not result in NTP mode 6
205 requests being sent to a server.
206 These are described following.
207 .Bl -tag -width "? [command_keyword]" -compact -offset indent
208 .It Ic ? Op Ar command_keyword
209 .It Ic help Op Ar command_keyword
212 by itself will print a list of all the command
213 keywords known to this incarnation of
217 followed by a command keyword will print function and usage
218 information about the command.
219 This command is probably a better
220 source of information about
224 .It Ic addvars Ar variable_name Ns Xo Op Ic =value
227 .It Ic rmvars Ar variable_name Ic ...
230 The data carried by NTP mode 6 messages consists of a list of
232 .Ql variable_name=value ,
235 is ignored, and can be omitted,
236 in requests to the server to read variables.
239 utility maintains an internal list in which data to be included in control
240 messages can be assembled, and sent using the
244 commands described below.
247 command allows variables and their optional values to be added to
249 If more than one variable is to be added, the list should
250 be comma-separated and not contain white space.
253 command can be used to remove individual variables from the list,
256 command removes all variables from the
260 command displays the current list of optional variables.
261 .It Ic authenticate Op yes | no
264 does not authenticate requests unless
265 they are write requests.
270 to send authentication with all requests it
272 Authenticated requests causes some servers to handle
273 requests slightly differently, and can occasionally melt the CPU in
274 fuzzballs if you turn authentication on before doing a
281 to display whether or not
283 is currently autheinticating requests.
285 Causes output from query commands to be "cooked", so that
286 variables which are recognized by
289 values reformatted for human consumption.
292 thinks should have a decodable value but didn't are
293 marked with a trailing
303 With no argument, displays the current debug level.
304 Otherwise, the debug level is changed to the indicated level.
305 .It Ic delay Ar milliseconds
306 Specify a time interval to be added to timestamps included in
307 requests which require authentication.
308 This is used to enable
309 (unreliable) server reconfiguration over long delay network paths
310 or between machines whose clocks are unsynchronized.
312 server does not now require timestamps in authenticated requests,
313 so this command may be obsolete.
317 .It Ic host Ar hostname
318 Set the host to which future queries will be sent.
320 may be either a host name or a numeric address.
321 .It Ic hostnames Op Cm yes | Cm no
324 is specified, host names are printed in
325 information displays.
328 is specified, numeric
329 addresses are printed instead.
333 modified using the command line
336 .It Ic keyid Ar keyid
337 This command allows the specification of a key number to be
338 used to authenticate configuration requests.
342 key number the server has been configured to use for this
346 .Cm OpenSSLDigestType
349 Specify the type of key to use for authenticating requests.
354 was built with OpenSSL support,
355 any digest type supported by OpenSSL can also be provided.
356 If no argument is given, the current
359 .It Ic ntpversion Xo Oo
366 Sets the NTP version number which
370 Defaults to 3, and note that mode 6 control messages (and
371 modes, for that matter) didn't exist in NTP version 1.
373 to be no servers left which demand version 1.
374 With no argument, displays the current NTP version that will be used
375 when communicating with servers.
377 This command prompts you to type in a password (which will not
378 be echoed) which will be used to authenticate configuration
380 The password must correspond to the key configured for
381 use by the NTP server for this purpose if such requests are to be
383 .\" Not yet implemented.
387 .\" Poll an NTP server in client mode
394 Causes all output from query commands is printed as received
395 from the remote server.
396 The only formating/interpretation done on
397 the data is to transform nonascii data into a printable (but barely
398 understandable) form.
399 .It Ic timeout Ar milliseconds
400 Specify a timeout period for responses to server queries.
402 default is about 5000 milliseconds.
405 retries each query once after a timeout, the total waiting time for
406 a timeout will be twice the timeout value set.
408 Print the version of the
413 .Ss "Control Message Commands"
414 Association IDs are used to identify system, peer and clock variables.
415 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.
416 Most control commands send a single mode-6 message to the server and expect a single response message.
417 The exceptions are the
419 command, which sends a series of messages,
424 commands, which iterate over a range of associations.
425 .Bl -tag -width "something" -compact -offset indent
427 Display a list of mobilized associations in the form:
428 .Dl ind assid status conf reach auth condition last_event cnt
429 .Bl -column -offset indent ".Sy Variable" ".Sy Description"
430 .It Sy String Ta Sy Description
431 .It Li ind Ta index on this list
432 .It Li assid Ta association ID
433 .It Li status Ta peer status word
434 .It Li conf Ta Li yes : persistent, Li no : ephemeral
435 .It Li reach Ta Li yes : reachable, Li no : unreachable
436 .It Li auth Ta Li ok , Li yes , Li bad and Li none
437 .It Li condition Ta selection status (see the Li select field of the peer status word)
438 .It Li last_event Ta event report (see the Li event field of the peer status word)
439 .It Li cnt Ta event count (see the Li count field of the peer status word)
442 Display the authentication statistics.
443 .It Cm clockvar Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
444 .It Cm cv Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
445 Display a list of clock variables for those associations supporting a reference clock.
446 .It Cm :config Op ...
447 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.
448 .It Cm config-from-file Ar filename
449 Send the each line of
451 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.
453 Display statistics for each local network address. Authentication is required.
455 Display network and reference clock I/O statistics.
457 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.
459 Perform the same function as the associations command, except display mobilized and unmobilized associations.
465 Obtain and print a list of all peers and clients showing
467 (associated with any given IP version).
473 Print a peer spreadsheet for the appropriate IP version(s).
475 (associated with any given IP version).
477 Display monitor facility statistics.
478 .It Ic mrulist Oo Ic limited | Ic kod | Ic mincount Ns = Ns Ar count | Ic laddr Ns = Ns Ar localaddr | Ic sort Ns = Ns Ar sortorder | Ic resany Ns = Ns Ar hexmask | Ic resall Ns = Ns Ar hexmask Oc
479 Obtain and print traffic counts collected and maintained by the monitor facility.
480 With the exception of
481 .Cm sort Ns = Ns Ar sortorder ,
482 the options filter the list returned by
488 options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
490 .Cm mincount Ns = Ns Ar count
491 option filters entries representing less than
495 .Cm laddr Ns = Ns Ar localaddr
496 option filters entries for packets received on any local address other than
498 .Cm resany Ns = Ns Ar hexmask
500 .Cm resall Ns = Ns Ar hexmask
501 filter entries containing none or less than all, respectively, of the bits in
503 which must begin with
514 or any of those preceded by a minus sign (hyphen) to reverse the sort order.
515 The output columns are:
516 .Bl -tag -width "something" -compact -offset indent
520 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
523 Average interval in s between packets from this address.
525 Restriction flags associated with this address.
526 Most are copied unchanged from the matching
528 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
530 Rate control indicator, either
535 for no rate control response,
536 rate limiting by discarding, or rate limiting with a KoD response, respectively.
540 Packet version number.
542 Packets received from this address.
544 Source port of last packet from this address.
545 .It Ic remote address
546 DNS name, numeric address, or address followed by
547 claimed DNS name which could not be verified in parentheses.
549 .It Ic mreadvar assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
550 .It Ic mrv assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
551 Perform the same function as the
553 command, except for a range of association IDs.
554 This range is determined from the association list cached by the most recent
562 Obtain and print the old-style list of all peers and clients showing
564 (associated with any given IP version),
568 Perform the same function as the
571 except that it uses previously stored data rather than making a new query.
573 Display a list of peers in the form:
574 .Dl [tally]remote refid st t when pool reach delay offset jitter
575 .Bl -tag -width "something" -compact -offset indent
579 single-character code indicating current value of the
582 .Lk decode.html#peer "peer status word"
584 host name (or IP number) of peer.
585 The value displayed will be truncated to 15 characters unless the
587 flag is given, in which case the full value will be displayed
589 and the remaining data is displayed on the next line.
592 .Lk decode.html#kiss "'kiss code"
597 unicast or manycast client,
599 broadcast or multicast client,
601 local (reference clock),
611 sec/min/hr since last received packet
613 poll interval (log2 s)
615 reach shift register (octal)
619 offset of server relative to this host
624 Display a list of peers in the form:
625 .Dl [tally]remote refid assid st t when pool reach delay offset jitter
626 where the output is just like the
628 command except that the
630 is displayed in hex format and the association number is also displayed.
631 .It Ic pstats Ar assocID
632 Show the statistics for the peer with the given
634 .It Ic readlist Ar assocID
636 Read the system or peer variables included in the variable list.
637 .It Ic readvar Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
638 .It Ic rv Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
639 Display the specified variables.
642 is zero, the variables are from the
644 name space, otherwise they are from the
649 is required, as the same name can occur in both spaces.
652 is included, all operative variables in the name space are displayed.
654 In this case only, if the
656 is omitted, it is assumed zero.
657 Multiple names are specified with comma separators and without whitespace.
658 Note that time values are represented in milliseconds
659 and frequency values in parts-per-million (PPM).
660 Some NTP timestamps are represented in the format
662 where YYYY is the year,
663 MM the month of year,
664 DD the day of month and
665 TTTT the time of day.
667 Show the access control (restrict) list for
670 .It Ic saveconfig Ar filename
671 Write the current configuration,
672 including any runtime modifications given with
675 .Ic config-from-file ,
676 to the ntpd host's file
678 This command will be rejected by the server unless
679 .Lk miscopt.html#saveconfigdir "saveconfigdir"
686 format specifies to substitute the current date and time, for example,
687 .Ic q]saveconfig ntp-%Y%m%d-%H%M%S.confq] .
688 The filename used is stored in system variable
690 Authentication is required.
692 Display interval timer counters.
693 .It Ic writelist Ar assocID
694 Write the system or peer variables included in the variable list.
695 .It Ic writevar Ar assocID Ar name Ns = Ns Ar value Op , ...
696 Write the specified variables.
699 is zero, the variables are from the
701 name space, otherwise they are from the
706 is required, as the same name can occur in both spaces.
708 Display operational summary.
710 Print statistics counters maintained in the protocol module.
713 .Ss Status Words and Kiss Codes
715 The current state of the operating program is shown
716 in a set of status words
717 maintained by the system.
718 Status information is also available on a per-association basis.
719 These words are displayed in the
723 commands both in hexadecimal and in decoded short tip strings.
724 The codes, tips and short explanations are documented on the
725 .Lk decode.html "Event Messages and Status Words"
727 The page also includes a list of system and peer messages,
728 the code for the latest of which is included in the status word.
730 Information resulting from protocol machine state transitions
731 is displayed using an informal set of ASCII strings called
732 .Lk decode.html#kiss "kiss codes" .
733 The original purpose was for kiss-o'-death (KoD) packets
734 sent by the server to advise the client of an unusual condition.
735 They are now displayed, when appropriate,
736 in the reference identifier field in various billboards.
739 The following system variables appear in the
742 Not all variables are displayed in some configurations.
743 .Bl -tag -width "something" -compact -offset indent
747 .Lk decode.html#sys "system status word"
749 NTP software version and build time
751 hardware platform and version
753 operating system and version
755 leap warning indicator (0-3)
761 total roundtrip delay to the primary reference clock
763 total dispersion to the primary reference clock
765 system peer association ID
767 time constant and poll exponent (log2 s) (3-17)
769 minimum time constant (log2 s) (3-10)
774 .Lk decode.html#kiss "kiss code"
778 combined offset of server relative to this host
780 combined system jitter
782 frequency offset (PPM) relative to hardware clock
784 clock frequency wander (PPM)
790 NTP seconds when the next leap second is/was inserted
792 NTP seconds when the NIST leapseconds file expires
794 The jitter and wander statistics are exponentially-weighted RMS averages.
795 The system jitter is defined in the NTPv4 specification;
796 the clock jitter statistic is computed by the clock discipline module.
798 When the NTPv4 daemon is compiled with the OpenSSL software library,
799 additional system variables are displayed,
800 including some or all of the following,
801 depending on the particular Autokey dance:
803 .Bl -tag -width "something" -compact -offset indent
807 Autokey host name for this host
809 Autokey group name for this host
811 host flags (see Autokey specification)
813 OpenSSL message digest algorithm
815 OpenSSL digest/signature scheme
817 NTP seconds at last signature update
819 certificate subject, issuer and certificate flags
821 NTP seconds when the certificate expires
824 The following peer variables appear in the
826 billboard for each association.
827 Not all variables are displayed in some configurations.
829 .Bl -tag -width "something" -compact -offset indent
835 .Lk decode.html#peer "peer status word"
837 source (remote) IP address
841 destination (local) IP address
843 destination (local) port
851 total roundtrip delay to the primary reference clock
853 total root dispersion to the primary reference clock
856 .Lk decode.html#kiss "kiss code"
860 reach register (octal)
868 host poll exponent (log2 s) (3-17)
870 peer poll exponent (log2 s) (3-17)
873 .Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
875 .Lk decode.html#flash "flash status word"
885 Autokey group name for this association
887 unicast/broadcast bias
889 interleave delay (see
890 .Lk xleave.html "NTP Interleaved Modes" )
894 variable is calculated when the first broadcast packet is received
895 after the calibration volley.
896 It represents the offset of the broadcast subgraph relative to the unicast subgraph.
899 variable appears only for the interleaved symmetric and interleaved modes.
900 It represents the internal queuing, buffering and transmission delays
901 for the preceding packet.
903 When the NTPv4 daemon is compiled with the OpenSSL software library,
904 additional peer variables are displayed, including the following:
905 .Bl -tag -width "something" -compact -offset indent
909 peer flags (see Autokey specification)
913 peer flags (see Autokey specification)
915 OpenSSL digest/signature scheme
921 Autokey signature timestamp
925 The following clock variables appear in the
927 billboard for each association with a reference clock.
928 Not all variables are displayed in some configurations.
929 .Bl -tag -width "something" -compact -offset indent
935 .Lk decode.html#clock "clock status word"
939 ASCII time code string (specific to device)
959 _END_PROG_MDOC_DESCRIP;