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.
328 to a key number the server has been configured to use for this
332 .Cm OpenSSLDigestType
335 Specify the type of key to use for authenticating requests.
340 was built with OpenSSL support,
341 any digest type supported by OpenSSL can also be provided.
342 If no argument is given, the current
345 .It Ic ntpversion Xo Oo
352 Sets the NTP version number which
356 Defaults to 3, and note that mode 6 control messages (and
357 modes, for that matter) didn't exist in NTP version 1.
359 to be no servers left which demand version 1.
360 With no argument, displays the current NTP version that will be used
361 when communicating with servers.
363 This command prompts you to type in a password (which will not
364 be echoed) which will be used to authenticate configuration
366 The password must correspond to the key configured for
367 use by the NTP server for this purpose if such requests are to be
369 .\" Not yet implemented.
373 .\" Poll an NTP server in client mode
380 Causes all output from query commands is printed as received
381 from the remote server.
382 The only formating/interpretation done on
383 the data is to transform nonascii data into a printable (but barely
384 understandable) form.
385 .It Ic timeout Ar milliseconds
386 Specify a timeout period for responses to server queries.
388 default is about 5000 milliseconds.
391 retries each query once after a timeout, the total waiting time for
392 a timeout will be twice the timeout value set.
394 Print the version of the
399 .Ss "Control Message Commands"
400 Association IDs are used to identify system, peer and clock variables.
401 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.
402 Most control commands send a single mode-6 message to the server and expect a single response message.
403 The exceptions are the
405 command, which sends a series of messages,
410 commands, which iterate over a range of associations.
411 .Bl -tag -width "something" -compact -offset indent
413 Display a list of mobilized associations in the form:
414 .Dl ind assid status conf reach auth condition last_event cnt
415 .Bl -column -offset indent ".Sy Variable" ".Sy Description"
416 .It Sy String Ta Sy Description
417 .It Li ind Ta index on this list
418 .It Li assid Ta association ID
419 .It Li status Ta peer status word
420 .It Li conf Ta Li yes : persistent, Li no : ephemeral
421 .It Li reach Ta Li yes : reachable, Li no : unreachable
422 .It Li auth Ta Li ok , Li yes , Li bad and Li none
423 .It Li condition Ta selection status (see the Li select field of the peer status word)
424 .It Li last_event Ta event report (see the Li event field of the peer status word)
425 .It Li cnt Ta event count (see the Li count field of the peer status word)
428 Display the authentication statistics.
429 .It Cm clockvar Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
430 .It Cm cv Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
431 Display a list of clock variables for those associations supporting a reference clock.
432 .It Cm :config Op ...
433 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.
434 .It Cm config-from-file Ar filename
435 Send the each line of
437 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.
439 Display statistics for each local network address. Authentication is required.
441 Display network and reference clock I/O statistics.
443 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.
445 Perform the same function as the associations command, except display mobilized and unmobilized associations.
451 Obtain and print a list of all peers and clients showing
453 (associated with any given IP version).
459 Print a peer spreadsheet for the appropriate IP version(s).
461 (associated with any given IP version).
463 Display monitor facility statistics.
464 .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
465 Obtain and print traffic counts collected and maintained by the monitor facility.
466 With the exception of
467 .Cm sort Ns = Ns Ar sortorder ,
468 the options filter the list returned by
474 options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
476 .Cm mincount Ns = Ns Ar count
477 option filters entries representing less than
481 .Cm laddr Ns = Ns Ar localaddr
482 option filters entries for packets received on any local address other than
484 .Cm resany Ns = Ns Ar hexmask
486 .Cm resall Ns = Ns Ar hexmask
487 filter entries containing none or less than all, respectively, of the bits in
489 which must begin with
500 or any of those preceded by a minus sign (hyphen) to reverse the sort order.
501 The output columns are:
502 .Bl -tag -width "something" -compact -offset indent
506 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
509 Average interval in s between packets from this address.
511 Restriction flags associated with this address.
512 Most are copied unchanged from the matching
514 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
516 Rate control indicator, either
521 for no rate control response,
522 rate limiting by discarding, or rate limiting with a KoD response, respectively.
526 Packet version number.
528 Packets received from this address.
530 Source port of last packet from this address.
531 .It Ic remote address
532 DNS name, numeric address, or address followed by
533 claimed DNS name which could not be verified in parentheses.
535 .It Ic mreadvar assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
536 .It Ic mrv assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
537 Perform the same function as the
539 command, except for a range of association IDs.
540 This range is determined from the association list cached by the most recent
548 Obtain and print the old-style list of all peers and clients showing
550 (associated with any given IP version),
554 Perform the same function as the
557 except that it uses previously stored data rather than making a new query.
559 Display a list of peers in the form:
560 .Dl [tally]remote refid st t when pool reach delay offset jitter
561 .Bl -tag -width "something" -compact -offset indent
565 single-character code indicating current value of the
568 .Lk decode.html#peer "peer status word"
570 host name (or IP number) of peer.
571 The value displayed will be truncated to 15 characters unless the
573 flag is given, in which case the full value will be displayed
575 and the remaining data is displayed on the next line.
578 .Lk decode.html#kiss "'kiss code"
583 unicast or manycast client,
585 broadcast or multicast client,
587 local (reference clock),
597 sec/min/hr since last received packet
599 poll interval (log2 s)
601 reach shift register (octal)
605 offset of server relative to this host
609 .It Ic pstats Ar assocID
610 Show the statistics for the peer with the given
612 .It Ic readlist Ar assocID
614 Read the system or peer variables included in the variable list.
615 .It Ic readvar Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
616 .It Ic rv Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
617 Display the specified variables.
620 is zero, the variables are from the
622 name space, otherwise they are from the
627 is required, as the same name can occur in both spaces.
630 is included, all operative variables in the name space are displayed.
632 In this case only, if the
634 is omitted, it is assumed zero.
635 Multiple names are specified with comma separators and without whitespace.
636 Note that time values are represented in milliseconds
637 and frequency values in parts-per-million (PPM).
638 Some NTP timestamps are represented in the format
640 where YYYY is the year,
641 MM the month of year,
642 DD the day of month and
643 TTTT the time of day.
645 Show the access control (restrict) list for
648 .It Ic saveconfig Ar filename
649 Write the current configuration,
650 including any runtime modifications given with
653 .Ic config-from-file ,
654 to the ntpd host's file
656 This command will be rejected by the server unless
657 .Lk miscopt.html#saveconfigdir "saveconfigdir"
664 format specifies to substitute the current date and time, for example,
665 .Ic q]saveconfig ntp-%Y%m%d-%H%M%S.confq] .
666 The filename used is stored in system variable
668 Authentication is required.
670 Display interval timer counters.
671 .It Ic writelist Ar assocID
672 Write the system or peer variables included in the variable list.
673 .It Ic writevar Ar assocID Ar name Ns = Ns Ar value Op , ...
674 Write the specified variables.
677 is zero, the variables are from the
679 name space, otherwise they are from the
684 is required, as the same name can occur in both spaces.
686 Display operational summary.
688 Print statistics counters maintained in the protocol module.
691 .Ss Status Words and Kiss Codes
693 The current state of the operating program is shown
694 in a set of status words
695 maintained by the system.
696 Status information is also available on a per-association basis.
697 These words are displayed in the
701 commands both in hexadecimal and in decoded short tip strings.
702 The codes, tips and short explanations are documented on the
703 .Lk decode.html "Event Messages and Status Words"
705 The page also includes a list of system and peer messages,
706 the code for the latest of which is included in the status word.
708 Information resulting from protocol machine state transitions
709 is displayed using an informal set of ASCII strings called
710 .Lk decode.html#kiss "kiss codes" .
711 The original purpose was for kiss-o'-death (KoD) packets
712 sent by the server to advise the client of an unusual condition.
713 They are now displayed, when appropriate,
714 in the reference identifier field in various billboards.
717 The following system variables appear in the
720 Not all variables are displayed in some configurations.
721 .Bl -tag -width "something" -compact -offset indent
725 .Lk decode.html#sys "system status word"
727 NTP software version and build time
729 hardware platform and version
731 operating system and version
733 leap warning indicator (0-3)
739 total roundtrip delay to the primary reference clock
741 total dispersion to the primary reference clock
743 system peer association ID
745 time constant and poll exponent (log2 s) (3-17)
747 minimum time constant (log2 s) (3-10)
752 .Lk decode.html#kiss "kiss code"
756 combined offset of server relative to this host
758 combined system jitter
760 frequency offset (PPM) relative to hardware clock
762 clock frequency wander (PPM)
768 NTP seconds when the next leap second is/was inserted
770 NTP seconds when the NIST leapseconds file expires
772 The jitter and wander statistics are exponentially-weighted RMS averages.
773 The system jitter is defined in the NTPv4 specification;
774 the clock jitter statistic is computed by the clock discipline module.
776 When the NTPv4 daemon is compiled with the OpenSSL software library,
777 additional system variables are displayed,
778 including some or all of the following,
779 depending on the particular Autokey dance:
781 .Bl -tag -width "something" -compact -offset indent
785 Autokey host name for this host
787 Autokey group name for this host
789 host flags (see Autokey specification)
791 OpenSSL message digest algorithm
793 OpenSSL digest/signature scheme
795 NTP seconds at last signature update
797 certificate subject, issuer and certificate flags
799 NTP seconds when the certificate expires
802 The following peer variables appear in the
804 billboard for each association.
805 Not all variables are displayed in some configurations.
807 .Bl -tag -width "something" -compact -offset indent
813 .Lk decode.html#peer "peer status word"
815 source (remote) IP address
819 destination (local) IP address
821 destination (local) port
829 total roundtrip delay to the primary reference clock
831 total root dispersion to the primary reference clock
834 .Lk decode.html#kiss "kiss code"
838 reach register (octal)
846 host poll exponent (log2 s) (3-17)
848 peer poll exponent (log2 s) (3-17)
851 .Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
853 .Lk decode.html#flash "flash status word"
863 Autokey group name for this association
865 unicast/broadcast bias
867 interleave delay (see
868 .Lk xleave.html "NTP Interleaved Modes" )
872 variable is calculated when the first broadcast packet is received
873 after the calibration volley.
874 It represents the offset of the broadcast subgraph relative to the unicast subgraph.
877 variable appears only for the interleaved symmetric and interleaved modes.
878 It represents the internal queuing, buffering and transmission delays
879 for the preceding packet.
881 When the NTPv4 daemon is compiled with the OpenSSL software library,
882 additional peer variables are displayed, including the following:
883 .Bl -tag -width "something" -compact -offset indent
887 peer flags (see Autokey specification)
891 peer flags (see Autokey specification)
893 OpenSSL digest/signature scheme
899 Autokey signature timestamp
903 The following clock variables appear in the
905 billboard for each association with a reference clock.
906 Not all variables are displayed in some configurations.
907 .Bl -tag -width "something" -compact -offset indent
913 .Lk decode.html#clock "clock status word"
917 ASCII time code string (specific to device)
937 _END_PROG_MDOC_DESCRIP;