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 name resolution";
19 Force resolution of following host names on the command line
20 to the IPv4 namespace.
28 descrip = "Force IPv6 name resolution";
30 Force 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 to monitor NTP operations
133 and performance, requesting
134 information about current state and/or changes in that state.
135 The program may be run either in interactive mode or controlled using
136 command line arguments.
137 Requests to read and write arbitrary
138 variables can be assembled, with raw and pretty-printed output
139 options being available.
142 utility can also obtain and print a
143 list of peers in a common format by sending multiple queries to the
146 If one or more request options is included on the command line
149 is executed, each of the requests will be sent
150 to the NTP servers running on each of the hosts given as command
151 line arguments, or on localhost by default.
152 If no request options
155 will attempt to read commands from the
156 standard input and execute these on the NTP server running on the
157 first host given on the command line, again defaulting to localhost
158 when no other host is specified.
161 utility will prompt for
162 commands if the standard input is a terminal device.
165 uses NTP mode 6 packets to communicate with the
166 NTP server, and hence can be used to query any compatible server on
167 the network which permits it.
168 Note that since NTP is a UDP protocol
169 this communication will be somewhat unreliable, especially over
170 large distances in terms of network topology.
174 one attempt to retransmit requests, and will time requests out if
175 the remote host is not heard from within a suitable timeout
178 Note that in contexts where a host name is expected, a
180 qualifier preceding the host name forces resolution to the IPv4
183 qualifier forces resolution to the IPv6 namespace.
184 For examples and usage, see the
185 .Dq NTP Debugging Techniques
189 command line option other than
194 cause the specified query (queries) to be sent to the indicated
199 interactive format commands from the standard input.
201 .Ss "Internal Commands"
203 Interactive format commands consist of a keyword followed by zero
205 Only enough characters of the full keyword to
206 uniquely identify the command need be typed.
209 number of interactive format commands are executed entirely within
212 utility itself and do not result in NTP
213 requests being sent to a server.
214 These are described following.
215 .Bl -tag -width "help [command]" -compact -offset indent
216 .It Ic ? Op Ar command
217 .It Ic help Op Ar command
220 by itself will print a list of all the commands
225 followed by a command name will print function and usage
226 information about the command.
227 .It Ic addvars Ar name Ns Oo \&= Ns Ar value Oc Ns Op ,...
228 .It Ic rmvars Ar name Ns Op ,...
231 The arguments to this command consist of a list of
233 .Ar name Ns Op \&= Ns Ar value ,
236 is ignored, and can be omitted,
237 in requests to the server to read variables.
240 utility maintains an internal list in which data to be included in
241 messages can be assembled, and displayed or set using the
245 commands described below.
248 command allows variables and their optional values to be added to
250 If more than one variable is to be added, the list should
251 be comma-separated and not contain white space.
254 command can be used to remove individual variables from the list,
257 command removes all variables from the
261 command displays the current list of optional variables.
262 .It Ic authenticate Op Cm yes Ns | Ns Cm no
265 does not authenticate requests unless
266 they are write requests.
268 .Ic authenticate Cm yes
271 to send authentication with all requests it
273 Authenticated requests causes some servers to handle
274 requests slightly differently.
279 to display whether or not
280 it is currently authenticating requests.
282 Causes output from query commands to be "cooked", so that
283 variables which are recognized by
286 values reformatted for human consumption.
289 could not decode completely are
290 marked with a trailing
292 .It Ic debug Op Cm more Ns | Ns Cm less Ns | Ns Cm off
293 With no argument, displays the current debug level.
294 Otherwise, the debugging level is changed as indicated.
295 .It Ic delay Op Ar milliseconds
296 Specify a time interval to be added to timestamps included in
297 requests which require authentication.
298 This is used to enable
299 (unreliable) server reconfiguration over long delay network paths
300 or between machines whose clocks are unsynchronized.
302 server does not now require timestamps in authenticated requests,
303 so this command may be obsolete.
304 Without any arguments, displays the current delay.
305 .It Ic drefid Op Cm hash Ns | Ns Cm ipv4
306 Display refids as IPv4 or hash.
307 Without any arguments, displays whether refids are shown as IPv4
312 .It Ic host Op Ar name
313 Set the host to which future queries will be sent.
316 may be either a host name or a numeric address.
317 Without any arguments, displays the current host.
318 .It Ic hostnames Op Cm yes Ns | Ns Cm no
321 is specified, host names are printed in
322 information displays.
325 is specified, numeric
326 addresses are printed instead.
330 modified using the command line
333 Without any arguments, displays whether host names or numeric addresses
335 .It Ic keyid Op Ar keyid
336 This command allows the specification of a key number to be
337 used to authenticate configuration requests.
341 key number the server has been configured to use for this
343 Without any arguments, displays the current
345 .It Ic keytype Op Ar digest
346 Specify the digest algorithm to use for authenticating requests, with default
350 was built with OpenSSL support, and OpenSSL is installed,
352 can be any message digest algorithm supported by OpenSSL.
353 If no argument is given, the current
354 .Ic keytype Ar digest
355 algorithm used is displayed.
356 .It Ic ntpversion Op Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3 Ns | Ns Cm 4
357 Sets the NTP version number which
361 Defaults to 3, and note that mode 6 control messages (and
362 modes, for that matter) didn't exist in NTP version 1.
364 to be no servers left which demand version 1.
365 With no argument, displays the current NTP version that will be used
366 when communicating with servers.
368 This command prompts you to type in a password (which will not
369 be echoed) which will be used to authenticate configuration
371 The password must correspond to the key configured for
372 use by the NTP server for this purpose if such requests are to be
374 .It Ic poll Oo Ar n Oc Op Cm verbose
375 Poll an NTP server in client mode
378 Poll not implemented yet.
383 Causes all output from query commands is printed as received
384 from the remote server.
385 The only formating/interpretation done on
386 the data is to transform nonascii data into a printable (but barely
387 understandable) form.
388 .It Ic timeout Op Ar milliseconds
389 Specify a timeout period for responses to server queries.
391 default is about 5000 milliseconds.
392 Without any arguments, displays the current timeout period.
395 retries each query once after a timeout, the total waiting time for
396 a timeout will be twice the timeout value set.
398 Display the version of the
403 .Ss "Control Message Commands"
404 Association ids are used to identify system, peer and clock variables.
405 System variables are assigned an association id of zero and system name
406 space, while each association is assigned a nonzero association id and
408 Most control commands send a single message to the server and expect a
409 single response message.
410 The exceptions are the
412 command, which sends a series of messages,
417 commands, which iterate over a range of associations.
418 .Bl -tag -width "something" -compact -offset indent
420 Display a list of peers in the form:
421 .Dl [tally]remote refid assid st t when pool reach delay offset jitter
422 where the output is just like the
424 command except that the
426 is displayed in hex format and the association number is also displayed.
428 Display a list of mobilized associations in the form:
429 .Dl ind assid status conf reach auth condition last_event cnt
430 .Bl -column -offset indent ".Sy Variable" "see the select field of the peer status word"
431 .It Sy Variable Ta Sy Description
432 .It Cm ind Ta index on this list
433 .It Cm assid Ta association id
434 .It Cm status Ta peer status word
435 .It Cm conf Ta Cm yes : No persistent, Cm no : No ephemeral
436 .It Cm reach Ta Cm yes : No reachable, Cm no : No unreachable
437 .It Cm auth Ta Cm ok , Cm yes , Cm bad No and Cm none
438 .It Cm condition Ta selection status \&(see the Cm select No field of the peer status word\&)
439 .It Cm last_event Ta event report \&(see the Cm event No field of the peer status word\&)
440 .It Cm cnt Ta event count \&(see the Cm count No field of the peer status word\&)
443 Display the authentication statistics counters:
444 time since reset, stored keys, free keys, key lookups, keys not found,
445 uncached keys, expired keys, encryptions, decryptions.
446 .It Ic clocklist Op Ar associd
447 .It Ic cl Op Ar associd
448 Display all clock variables in the variable list for those associations
449 supporting a reference clock.
450 .It Ic clockvar Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,...
451 .It Ic cv Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,...
452 Display a list of clock variables for those associations supporting a
454 .It Ic :config Ar "configuration command line"
455 Send the remainder of the command line, including whitespace, to the
456 server as a run-time configuration command in the same format as a line
457 in the configuration file.
458 This command is experimental until further notice and clarification.
459 Authentication is of course required.
460 .It Ic config-from-file Ar filename
463 to the server as run-time configuration commands in the same format as
464 lines in the configuration file.
465 This command is experimental until further notice and clarification.
466 Authentication is required.
468 Display status and statistics counters for each local network interface address:
469 interface number, interface name and address or broadcast, drop, flag,
470 ttl, mc, received, sent, send failed, peers, uptime.
471 Authentication is required.
473 Display network and reference clock I/O statistics:
474 time since reset, receive buffers, free receive buffers, used receive buffers,
475 low water refills, dropped packets, ignored packets, received packets,
476 packets sent, packet send failures, input wakeups, useful input wakeups.
478 Display kernel loop and PPS statistics:
479 associd, status, pll offset, pll frequency, maximum error,
480 estimated error, kernel status, pll time constant, precision,
481 frequency tolerance, pps frequency, pps stability, pps jitter,
482 calibration interval, calibration cycles, jitter exceeded,
483 stability exceeded, calibration errors.
484 As with other ntpq output, times are in milliseconds; very small values
485 may be shown as exponentials.
486 The precision value displayed is in milliseconds as well, unlike the
487 precision system variable.
489 Perform the same function as the associations command, except display
490 mobilized and unmobilized associations, including all clients.
491 .It Ic lopeers Op Fl 4 Ns | Ns Fl 6
492 Display a list of all peers and clients showing
494 (associated with the given IP version).
495 .It Ic lpassociations
496 Display the last obtained list of associations, including all clients.
497 .It Ic lpeers Op Fl 4 Ns | Ns Fl 6
498 Display a list of all peers and clients (associated with the given IP version).
500 Display monitor facility status, statistics, and limits:
501 enabled, addresses, peak addresses, maximum addresses,
502 reclaim above count, reclaim older than, kilobytes, maximum kilobytes.
503 .It Ic mreadlist Ar associdlo Ar associdhi
504 .It Ic mrl Ar associdlo Ar associdhi
505 Perform the same function as the
507 command for a range of association ids.
508 .It Ic mreadvar Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,...
509 This range may be determined from the list displayed by any
510 command showing associations.
511 .It Ic mrv Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,...
512 Perform the same function as the
514 command for a range of association ids.
515 This range may be determined from the list displayed by any
516 command showing associations.
517 .It Xo Ic mrulist Oo Cm limited | Cm kod | Cm mincount Ns \&= Ns Ar count |
518 .Cm laddr Ns \&= Ns Ar localaddr | Cm sort Ns \&= Ns Oo \&- Oc Ns Ar sortorder |
519 .Cm resany Ns \&= Ns Ar hexmask | Cm resall Ns \&= Ns Ar hexmask Oc
521 Display traffic counts of the most recently seen source addresses
522 collected and maintained by the monitor facility.
523 With the exception of
524 .Cm sort Ns \&= Ns Oo \&- Oc Ns Ar sortorder ,
525 the options filter the list returned by
531 options return only entries representing client addresses from which the
532 last packet received triggered either discarding or a KoD response.
534 .Cm mincount Ns = Ns Ar count
535 option filters entries representing less than
539 .Cm laddr Ns = Ns Ar localaddr
540 option filters entries for packets received on any local address other than
542 .Cm resany Ns = Ns Ar hexmask
544 .Cm resall Ns = Ns Ar hexmask
545 filter entries containing none or less than all, respectively, of the bits in
547 which must begin with
558 or any of those preceded by
560 to reverse the sort order.
561 The output columns are:
562 .Bl -tag -width "something" -compact -offset indent
566 Interval in seconds between the receipt of the most recent packet from
567 this address and the completion of the retrieval of the MRU list by
570 Average interval in s between packets from this address.
572 Restriction flags associated with this address.
573 Most are copied unchanged from the matching
575 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless
576 the last packet from this address triggered a rate control response.
578 Rate control indicator, either
583 for no rate control response,
584 rate limiting by discarding, or rate limiting with a KoD response, respectively.
588 Packet version number.
590 Packets received from this address.
592 Source port of last packet from this address.
593 .It Ic remote address
594 host or DNS name, numeric address, or address followed by
595 claimed DNS name which could not be verified in parentheses.
597 .It Ic opeers Op Fl 4 | Fl 6
598 Obtain and print the old-style list of all peers and clients showing
600 (associated with the given IP version),
604 Perform the same function as the
607 except that it uses previously stored data rather than making a new query.
609 Display a list of peers in the form:
610 .Dl [tally]remote refid st t when pool reach delay offset jitter
611 .Bl -tag -width "something" -compact -offset indent
615 single-character code indicating current value of the
618 .Lk decode.html#peer "peer status word"
620 host name (or IP number) of peer.
621 The value displayed will be truncated to 15 characters unless the
624 option is given, in which case the full value will be displayed
625 on the first line, and if too long,
626 the remaining data will be displayed on the next line.
629 .Lk decode.html#kiss "'kiss code"
631 stratum: 0 for local reference clocks, 1 for servers with local
632 reference clocks, ..., 16 for unsynchronized server clocks
635 unicast or manycast client,
637 broadcast or multicast client,
641 local (reference clock),
651 time in seconds, minutes, hours, or days since the last packet
654 if a packet has never been received
658 reach shift register (octal)
662 offset of server relative to this host
664 offset RMS error estimate.
666 .It Ic pstats Ar associd
667 Display the statistics for the peer with the given
669 associd, status, remote host, local address, time last received,
670 time until next send, reachability change, packets sent,
671 packets received, bad authentication, bogus origin, duplicate,
672 bad dispersion, bad reference time, candidate order.
673 .It Ic readlist Op Ar associd
674 .It Ic rl Op Ar associd
675 Display all system or peer variables.
678 is omitted, it is assumed to be zero.
679 .It Ic readvar Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ...
680 .It Ic rv Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ...
681 Display the specified system or peer variables.
684 is zero, the variables are from the
686 name space, otherwise they are from the
691 is required, as the same name can occur in both spaces.
694 is included, all operative variables in the name space are displayed.
695 In this case only, if the
697 is omitted, it is assumed to be zero.
698 Multiple names are specified with comma separators and without whitespace.
699 Note that time values are represented in milliseconds
700 and frequency values in parts-per-million (PPM).
701 Some NTP timestamps are represented in the format
702 .Ar YYYY Ns Ar MM Ar DD Ar TTTT ,
713 Display the access control (restrict) list for
715 Authentication is required.
716 .It Ic saveconfig Ar filename
717 Save the current configuration,
718 including any runtime modifications made by
721 .Ic config-from-file ,
722 to the NTP server host file
724 This command will be rejected by the server unless
725 .Lk miscopt.html#saveconfigdir "saveconfigdir"
732 format specifiers to substitute the current date and time, for
734 .D1 Ic saveconfig Pa ntp-%Y%m%d-%H%M%S.conf .
735 The filename used is stored in system variable
737 Authentication is required.
739 Display system operational summary:
740 associd, status, system peer, system peer mode, leap indicator,
741 stratum, log2 precision, root delay, root dispersion,
742 reference id, reference time, system jitter, clock jitter,
743 clock wander, broadcast delay, symm. auth. delay.
745 Display system uptime and packet counts maintained in the
747 uptime, sysstats reset, packets received, current version,
748 older version, bad length or format, authentication failed,
749 declined, restricted, rate limited, KoD responses,
752 Display interval timer counters:
753 time since reset, timer overruns, calls to transmit.
754 .It Ic writelist Ar associd
755 Set all system or peer variables included in the variable list.
756 .It Ic writevar Ar associd Ar name Ns = Ns Ar value Op , ...
757 Set the specified variables in the variable list.
760 is zero, the variables are from the
762 name space, otherwise they are from the
767 is required, as the same name can occur in both spaces.
768 Authentication is required.
771 .Ss Status Words and Kiss Codes
772 The current state of the operating program is shown
773 in a set of status words
774 maintained by the system.
775 Status information is also available on a per-association basis.
776 These words are displayed by the
780 commands both in hexadecimal and in decoded short tip strings.
781 The codes, tips and short explanations are documented on the
782 .Lk decode.html "Event Messages and Status Words"
784 The page also includes a list of system and peer messages,
785 the code for the latest of which is included in the status word.
787 Information resulting from protocol machine state transitions
788 is displayed using an informal set of ASCII strings called
789 .Lk decode.html#kiss "kiss codes" .
790 The original purpose was for kiss-o'-death (KoD) packets
791 sent by the server to advise the client of an unusual condition.
792 They are now displayed, when appropriate,
793 in the reference identifier field in various billboards.
796 The following system variables appear in the
799 Not all variables are displayed in some configurations.
801 .Bl -tag -width "something" -compact -offset indent
805 .Lk decode.html#sys "system status word"
807 NTP software version and build time
809 hardware platform and version
811 operating system and version
813 leap warning indicator (0-3)
819 total roundtrip delay to the primary reference clock
821 total dispersion to the primary reference clock
824 .Lk decode.html#kiss "kiss code"
830 system peer association id
832 time constant and poll exponent (log2 s) (3-17)
834 minimum time constant (log2 s) (3-10)
836 combined offset of server relative to this host
838 frequency drift (PPM) relative to hardware clock
840 combined system jitter
842 clock frequency wander (PPM)
848 NTP seconds when the next leap second is/was inserted
850 NTP seconds when the NIST leapseconds file expires
852 The jitter and wander statistics are exponentially-weighted RMS averages.
853 The system jitter is defined in the NTPv4 specification;
854 the clock jitter statistic is computed by the clock discipline module.
856 When the NTPv4 daemon is compiled with the OpenSSL software library,
857 additional system variables are displayed,
858 including some or all of the following,
859 depending on the particular Autokey dance:
860 .Bl -tag -width "something" -compact -offset indent
864 Autokey host name for this host
866 Autokey group name for this host
868 host flags (see Autokey specification)
870 OpenSSL message digest algorithm
872 OpenSSL digest/signature scheme
874 NTP seconds at last signature update
876 certificate subject, issuer and certificate flags
878 NTP seconds when the certificate expires
881 The following peer variables appear in the
883 billboard for each association.
884 Not all variables are displayed in some configurations.
886 .Bl -tag -width "something" -compact -offset indent
892 .Lk decode.html#peer "peer status word"
894 source (remote) IP address
898 destination (local) IP address
900 destination (local) port
908 total roundtrip delay to the primary reference clock
910 total root dispersion to the primary reference clock
913 .Lk decode.html#kiss "kiss code"
917 last packet received time
919 reach register (octal)
927 host poll exponent (log2 s) (3-17)
929 peer poll exponent (log2 s) (3-17)
932 .Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
934 .Lk decode.html#flash "flash status word"
946 unicast/broadcast bias
948 interleave delay (see
949 .Lk xleave.html "NTP Interleaved Modes" )
953 variable is calculated when the first broadcast packet is received
954 after the calibration volley.
955 It represents the offset of the broadcast subgraph relative to the
959 variable appears only for the interleaved symmetric and interleaved modes.
960 It represents the internal queuing, buffering and transmission delays
961 for the preceding packet.
963 When the NTPv4 daemon is compiled with the OpenSSL software library,
964 additional peer variables are displayed, including the following:
965 .Bl -tag -width "something" -compact -offset indent
969 peer flags (see Autokey specification)
973 peer flags (see Autokey specification)
975 OpenSSL digest/signature scheme
981 Autokey signature timestamp
983 Autokey group name for this association
987 The following clock variables appear in the
989 billboard for each association with a reference clock.
990 Not all variables are displayed in some configurations.
991 .Bl -tag -width "something" -compact -offset indent
997 .Lk decode.html#clock "clock status word"
1001 ASCII time code string (specific to device)
1021 _END_PROG_MDOC_DESCRIP;