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 = "Display the full 'remote' value";
107 Display the full value of the 'remote' value. If this requires
108 more than 15 characters, display the full value, emit a newline,
109 and continue the data display properly indented on the next line.
114 ds-type = 'DESCRIPTION';
116 ds-text = <<- _END_PROG_MDOC_DESCRIP
120 utility program is used to query NTP servers which
121 implement the standard NTP mode 6 control message formats defined
122 in Appendix B of the NTPv3 specification RFC1305, requesting
123 information about current state and/or changes in that state.
124 The same formats are used in NTPv4, although some of the
125 variables have changed and new ones added. The description on this
126 page is for the NTPv4 variables.
127 The program may be run either in interactive mode or controlled using
128 command line arguments.
129 Requests to read and write arbitrary
130 variables can be assembled, with raw and pretty-printed output
131 options being available.
134 utility can also obtain and print a
135 list of peers in a common format by sending multiple queries to the
138 If one or more request options is included on the command line
141 is executed, each of the requests will be sent
142 to the NTP servers running on each of the hosts given as command
143 line arguments, or on localhost by default.
144 If no request options
147 will attempt to read commands from the
148 standard input and execute these on the NTP server running on the
149 first host given on the command line, again defaulting to localhost
150 when no other host is specified.
153 utility will prompt for
154 commands if the standard input is a terminal device.
157 uses NTP mode 6 packets to communicate with the
158 NTP server, and hence can be used to query any compatible server on
159 the network which permits it.
160 Note that since NTP is a UDP protocol
161 this communication will be somewhat unreliable, especially over
162 large distances in terms of network topology.
166 one attempt to retransmit requests, and will time requests out if
167 the remote host is not heard from within a suitable timeout
171 command line option other than
176 cause the specified query (queries) to be sent to the indicated
181 interactive format commands from the standard input.
182 .Ss "Internal Commands"
183 Interactive format commands consist of a keyword followed by zero
185 Only enough characters of the full keyword to
186 uniquely identify the command need be typed.
189 number of interactive format commands are executed entirely within
192 utility itself and do not result in NTP mode 6
193 requests being sent to a server.
194 These are described following.
195 .Bl -tag -width "? [command_keyword]" -compact -offset indent
196 .It Ic ? Op Ar command_keyword
197 .It Ic help Op Ar command_keyword
200 by itself will print a list of all the command
201 keywords known to this incarnation of
205 followed by a command keyword will print function and usage
206 information about the command.
207 This command is probably a better
208 source of information about
212 .It Ic addvars Ar variable_name Ns Xo Op Ic =value
215 .It Ic rmvars Ar variable_name Ic ...
218 The data carried by NTP mode 6 messages consists of a list of
220 .Ql variable_name=value ,
223 is ignored, and can be omitted,
224 in requests to the server to read variables.
227 utility maintains an internal list in which data to be included in control
228 messages can be assembled, and sent using the
232 commands described below.
235 command allows variables and their optional values to be added to
237 If more than one variable is to be added, the list should
238 be comma-separated and not contain white space.
241 command can be used to remove individual variables from the list,
244 command removes all variables from the
248 command displays the current list of optional variables.
249 .It Ic authenticate Op yes | no
252 does not authenticate requests unless
253 they are write requests.
258 to send authentication with all requests it
260 Authenticated requests causes some servers to handle
261 requests slightly differently, and can occasionally melt the CPU in
262 fuzzballs if you turn authentication on before doing a
269 to display whether or not
271 is currently autheinticating requests.
273 Causes output from query commands to be "cooked", so that
274 variables which are recognized by
277 values reformatted for human consumption.
280 thinks should have a decodable value but didn't are
281 marked with a trailing
291 With no argument, displays the current debug level.
292 Otherwise, the debug level is changed to the indicated level.
293 .It Ic delay Ar milliseconds
294 Specify a time interval to be added to timestamps included in
295 requests which require authentication.
296 This is used to enable
297 (unreliable) server reconfiguration over long delay network paths
298 or between machines whose clocks are unsynchronized.
300 server does not now require timestamps in authenticated requests,
301 so this command may be obsolete.
305 .It Ic host Ar hostname
306 Set the host to which future queries will be sent.
308 may be either a host name or a numeric address.
309 .It Ic hostnames Op Cm yes | Cm no
312 is specified, host names are printed in
313 information displays.
316 is specified, numeric
317 addresses are printed instead.
321 modified using the command line
324 .It Ic keyid Ar keyid
325 This command allows the specification of a key number to be
326 used to authenticate configuration requests.
330 key number the server has been configured to use for this
334 .Cm OpenSSLDigestType
337 Specify the type of key to use for authenticating requests.
342 was built with OpenSSL support,
343 any digest type supported by OpenSSL can also be provided.
344 If no argument is given, the current
347 .It Ic ntpversion Xo Oo
354 Sets the NTP version number which
358 Defaults to 3, and note that mode 6 control messages (and
359 modes, for that matter) didn't exist in NTP version 1.
361 to be no servers left which demand version 1.
362 With no argument, displays the current NTP version that will be used
363 when communicating with servers.
365 This command prompts you to type in a password (which will not
366 be echoed) which will be used to authenticate configuration
368 The password must correspond to the key configured for
369 use by the NTP server for this purpose if such requests are to be
371 .\" Not yet implemented.
375 .\" Poll an NTP server in client mode
382 Causes all output from query commands is printed as received
383 from the remote server.
384 The only formating/interpretation done on
385 the data is to transform nonascii data into a printable (but barely
386 understandable) form.
387 .It Ic timeout Ar milliseconds
388 Specify a timeout period for responses to server queries.
390 default is about 5000 milliseconds.
393 retries each query once after a timeout, the total waiting time for
394 a timeout will be twice the timeout value set.
396 Print the version of the
401 .Ss "Control Message Commands"
402 Association IDs are used to identify system, peer and clock variables.
403 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.
404 Most control commands send a single mode-6 message to the server and expect a single response message.
405 The exceptions are the
407 command, which sends a series of messages,
412 commands, which iterate over a range of associations.
413 .Bl -tag -width "something" -compact -offset indent
415 Display a list of mobilized associations in the form:
416 .Dl ind assid status conf reach auth condition last_event cnt
417 .Bl -column -offset indent ".Sy Variable" ".Sy Description"
418 .It Sy String Ta Sy Description
419 .It Li ind Ta index on this list
420 .It Li assid Ta association ID
421 .It Li status Ta peer status word
422 .It Li conf Ta Li yes : persistent, Li no : ephemeral
423 .It Li reach Ta Li yes : reachable, Li no : unreachable
424 .It Li auth Ta Li ok , Li yes , Li bad and Li none
425 .It Li condition Ta selection status (see the Li select field of the peer status word)
426 .It Li last_event Ta event report (see the Li event field of the peer status word)
427 .It Li cnt Ta event count (see the Li count field of the peer status word)
430 Display the authentication statistics.
431 .It Cm clockvar Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
432 .It Cm cv Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
433 Display a list of clock variables for those associations supporting a reference clock.
434 .It Cm :config Op ...
435 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.
436 .It Cm config-from-file Ar filename
437 Send the each line of
439 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.
441 Display statistics for each local network address. Authentication is required.
443 Display network and reference clock I/O statistics.
445 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.
447 Perform the same function as the associations command, except display mobilized and unmobilized associations.
453 Obtain and print a list of all peers and clients showing
455 (associated with any given IP version).
461 Print a peer spreadsheet for the appropriate IP version(s).
463 (associated with any given IP version).
465 Display monitor facility statistics.
466 .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
467 Obtain and print traffic counts collected and maintained by the monitor facility.
468 With the exception of
469 .Cm sort Ns = Ns Ar sortorder ,
470 the options filter the list returned by
476 options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
478 .Cm mincount Ns = Ns Ar count
479 option filters entries representing less than
483 .Cm laddr Ns = Ns Ar localaddr
484 option filters entries for packets received on any local address other than
486 .Cm resany Ns = Ns Ar hexmask
488 .Cm resall Ns = Ns Ar hexmask
489 filter entries containing none or less than all, respectively, of the bits in
491 which must begin with
502 or any of those preceded by a minus sign (hyphen) to reverse the sort order.
503 The output columns are:
504 .Bl -tag -width "something" -compact -offset indent
508 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
511 Average interval in s between packets from this address.
513 Restriction flags associated with this address.
514 Most are copied unchanged from the matching
516 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
518 Rate control indicator, either
523 for no rate control response,
524 rate limiting by discarding, or rate limiting with a KoD response, respectively.
528 Packet version number.
530 Packets received from this address.
532 Source port of last packet from this address.
533 .It Ic remote address
534 DNS name, numeric address, or address followed by
535 claimed DNS name which could not be verified in parentheses.
537 .It Ic mreadvar assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
538 .It Ic mrv assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
539 Perform the same function as the
541 command, except for a range of association IDs.
542 This range is determined from the association list cached by the most recent
550 Obtain and print the old-style list of all peers and clients showing
552 (associated with any given IP version),
556 Perform the same function as the
559 except that it uses previously stored data rather than making a new query.
561 Display a list of peers in the form:
562 .Dl [tally]remote refid st t when pool reach delay offset jitter
563 .Bl -tag -width "something" -compact -offset indent
567 single-character code indicating current value of the
570 .Lk decode.html#peer "peer status word"
572 host name (or IP number) of peer.
573 The value displayed will be truncated to 15 characters unless the
575 flag is given, in which case the full value will be displayed
577 and the remaining data is displayed on the next line.
580 .Lk decode.html#kiss "'kiss code"
585 unicast or manycast client,
587 broadcast or multicast client,
589 local (reference clock),
599 sec/min/hr since last received packet
601 poll interval (log2 s)
603 reach shift register (octal)
607 offset of server relative to this host
612 Display a list of peers in the form:
613 .Dl [tally]remote refid assid st t when pool reach delay offset jitter
614 where the output is just like the
616 command except that the
618 is displayed in hex format and the association number is also displayed.
619 .It Ic pstats Ar assocID
620 Show the statistics for the peer with the given
622 .It Ic readlist Ar assocID
624 Read the system or peer variables included in the variable list.
625 .It Ic readvar Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
626 .It Ic rv Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
627 Display the specified variables.
630 is zero, the variables are from the
632 name space, otherwise they are from the
637 is required, as the same name can occur in both spaces.
640 is included, all operative variables in the name space are displayed.
642 In this case only, if the
644 is omitted, it is assumed zero.
645 Multiple names are specified with comma separators and without whitespace.
646 Note that time values are represented in milliseconds
647 and frequency values in parts-per-million (PPM).
648 Some NTP timestamps are represented in the format
650 where YYYY is the year,
651 MM the month of year,
652 DD the day of month and
653 TTTT the time of day.
655 Show the access control (restrict) list for
658 .It Ic saveconfig Ar filename
659 Write the current configuration,
660 including any runtime modifications given with
663 .Ic config-from-file ,
664 to the ntpd host's file
666 This command will be rejected by the server unless
667 .Lk miscopt.html#saveconfigdir "saveconfigdir"
674 format specifies to substitute the current date and time, for example,
675 .Ic q]saveconfig ntp-%Y%m%d-%H%M%S.confq] .
676 The filename used is stored in system variable
678 Authentication is required.
680 Display interval timer counters.
681 .It Ic writelist Ar assocID
682 Write the system or peer variables included in the variable list.
683 .It Ic writevar Ar assocID Ar name Ns = Ns Ar value Op , ...
684 Write the specified variables.
687 is zero, the variables are from the
689 name space, otherwise they are from the
694 is required, as the same name can occur in both spaces.
696 Display operational summary.
698 Print statistics counters maintained in the protocol module.
701 .Ss Status Words and Kiss Codes
703 The current state of the operating program is shown
704 in a set of status words
705 maintained by the system.
706 Status information is also available on a per-association basis.
707 These words are displayed in the
711 commands both in hexadecimal and in decoded short tip strings.
712 The codes, tips and short explanations are documented on the
713 .Lk decode.html "Event Messages and Status Words"
715 The page also includes a list of system and peer messages,
716 the code for the latest of which is included in the status word.
718 Information resulting from protocol machine state transitions
719 is displayed using an informal set of ASCII strings called
720 .Lk decode.html#kiss "kiss codes" .
721 The original purpose was for kiss-o'-death (KoD) packets
722 sent by the server to advise the client of an unusual condition.
723 They are now displayed, when appropriate,
724 in the reference identifier field in various billboards.
727 The following system variables appear in the
730 Not all variables are displayed in some configurations.
731 .Bl -tag -width "something" -compact -offset indent
735 .Lk decode.html#sys "system status word"
737 NTP software version and build time
739 hardware platform and version
741 operating system and version
743 leap warning indicator (0-3)
749 total roundtrip delay to the primary reference clock
751 total dispersion to the primary reference clock
753 system peer association ID
755 time constant and poll exponent (log2 s) (3-17)
757 minimum time constant (log2 s) (3-10)
762 .Lk decode.html#kiss "kiss code"
766 combined offset of server relative to this host
768 combined system jitter
770 frequency offset (PPM) relative to hardware clock
772 clock frequency wander (PPM)
778 NTP seconds when the next leap second is/was inserted
780 NTP seconds when the NIST leapseconds file expires
782 The jitter and wander statistics are exponentially-weighted RMS averages.
783 The system jitter is defined in the NTPv4 specification;
784 the clock jitter statistic is computed by the clock discipline module.
786 When the NTPv4 daemon is compiled with the OpenSSL software library,
787 additional system variables are displayed,
788 including some or all of the following,
789 depending on the particular Autokey dance:
791 .Bl -tag -width "something" -compact -offset indent
795 Autokey host name for this host
797 Autokey group name for this host
799 host flags (see Autokey specification)
801 OpenSSL message digest algorithm
803 OpenSSL digest/signature scheme
805 NTP seconds at last signature update
807 certificate subject, issuer and certificate flags
809 NTP seconds when the certificate expires
812 The following peer variables appear in the
814 billboard for each association.
815 Not all variables are displayed in some configurations.
817 .Bl -tag -width "something" -compact -offset indent
823 .Lk decode.html#peer "peer status word"
825 source (remote) IP address
829 destination (local) IP address
831 destination (local) port
839 total roundtrip delay to the primary reference clock
841 total root dispersion to the primary reference clock
844 .Lk decode.html#kiss "kiss code"
848 reach register (octal)
856 host poll exponent (log2 s) (3-17)
858 peer poll exponent (log2 s) (3-17)
861 .Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
863 .Lk decode.html#flash "flash status word"
873 Autokey group name for this association
875 unicast/broadcast bias
877 interleave delay (see
878 .Lk xleave.html "NTP Interleaved Modes" )
882 variable is calculated when the first broadcast packet is received
883 after the calibration volley.
884 It represents the offset of the broadcast subgraph relative to the unicast subgraph.
887 variable appears only for the interleaved symmetric and interleaved modes.
888 It represents the internal queuing, buffering and transmission delays
889 for the preceding packet.
891 When the NTPv4 daemon is compiled with the OpenSSL software library,
892 additional peer variables are displayed, including the following:
893 .Bl -tag -width "something" -compact -offset indent
897 peer flags (see Autokey specification)
901 peer flags (see Autokey specification)
903 OpenSSL digest/signature scheme
909 Autokey signature timestamp
913 The following clock variables appear in the
915 billboard for each association with a reference clock.
916 Not all variables are displayed in some configurations.
917 .Bl -tag -width "something" -compact -offset indent
923 .Lk decode.html#clock "clock status word"
927 ASCII time code string (specific to device)
947 _END_PROG_MDOC_DESCRIP;