2 .Dt NTPQ @NTPQ_MS@ User Commands
4 .\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc)
6 .\" It has been AutoGen-ed April 26, 2016 at 08:29:41 PM by AutoGen 5.18.5
7 .\" From the definitions ntpq-opts.def
8 .\" and the template file agmdoc-cmd.tpl
11 .Nd standard NTP query program
14 .\" Mixture of short (flag) options and long options
16 .Op Fl flag Op Ar value
17 .Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
23 utility program is used to query NTP servers which
24 implement the standard NTP mode 6 control message formats defined
25 in Appendix B of the NTPv3 specification RFC1305, requesting
26 information about current state and/or changes in that state.
27 The same formats are used in NTPv4, although some of the
28 variables have changed and new ones added. The description on this
29 page is for the NTPv4 variables.
30 The program may be run either in interactive mode or controlled using
31 command line arguments.
32 Requests to read and write arbitrary
33 variables can be assembled, with raw and pretty\-printed output
34 options being available.
37 utility can also obtain and print a
38 list of peers in a common format by sending multiple queries to the
40 If one or more request options is included on the command line
43 is executed, each of the requests will be sent
44 to the NTP servers running on each of the hosts given as command
45 line arguments, or on localhost by default.
49 will attempt to read commands from the
50 standard input and execute these on the NTP server running on the
51 first host given on the command line, again defaulting to localhost
52 when no other host is specified.
55 utility will prompt for
56 commands if the standard input is a terminal device.
58 uses NTP mode 6 packets to communicate with the
59 NTP server, and hence can be used to query any compatible server on
60 the network which permits it.
61 Note that since NTP is a UDP protocol
62 this communication will be somewhat unreliable, especially over
63 large distances in terms of network topology.
67 one attempt to retransmit requests, and will time requests out if
68 the remote host is not heard from within a suitable timeout
71 command line option other than
76 cause the specified query (queries) to be sent to the indicated
81 interactive format commands from the standard input.
82 .Ss "Internal Commands"
83 Interactive format commands consist of a keyword followed by zero
85 Only enough characters of the full keyword to
86 uniquely identify the command need be typed.
88 number of interactive format commands are executed entirely within
91 utility itself and do not result in NTP mode 6
92 requests being sent to a server.
93 These are described following.
94 .Bl -tag -width "? [command_keyword]" -compact -offset indent
95 .It Ic ? Op Ar command_keyword
96 .It Ic help Op Ar command_keyword
99 by itself will print a list of all the command
100 keywords known to this incarnation of
104 followed by a command keyword will print function and usage
105 information about the command.
106 This command is probably a better
107 source of information about
111 .It Ic addvars Ar variable_name Ns Xo Op Ic =value
114 .It Ic rmvars Ar variable_name Ic ...
117 The data carried by NTP mode 6 messages consists of a list of
119 .Ql variable_name=value ,
122 is ignored, and can be omitted,
123 in requests to the server to read variables.
126 utility maintains an internal list in which data to be included in control
127 messages can be assembled, and sent using the
131 commands described below.
134 command allows variables and their optional values to be added to
136 If more than one variable is to be added, the list should
137 be comma\-separated and not contain white space.
140 command can be used to remove individual variables from the list,
143 command removes all variables from the
147 command displays the current list of optional variables.
148 .It Ic authenticate Op yes | no
151 does not authenticate requests unless
152 they are write requests.
157 to send authentication with all requests it
159 Authenticated requests causes some servers to handle
160 requests slightly differently, and can occasionally melt the CPU in
161 fuzzballs if you turn authentication on before doing a
168 to display whether or not
170 is currently autheinticating requests.
172 Causes output from query commands to be "cooked", so that
173 variables which are recognized by
176 values reformatted for human consumption.
179 thinks should have a decodable value but didn't are
180 marked with a trailing
190 With no argument, displays the current debug level.
191 Otherwise, the debug level is changed to the indicated level.
192 .It Ic delay Ar milliseconds
193 Specify a time interval to be added to timestamps included in
194 requests which require authentication.
195 This is used to enable
196 (unreliable) server reconfiguration over long delay network paths
197 or between machines whose clocks are unsynchronized.
199 server does not now require timestamps in authenticated requests,
200 so this command may be obsolete.
204 .It Ic host Ar hostname
205 Set the host to which future queries will be sent.
207 may be either a host name or a numeric address.
208 .It Ic hostnames Op Cm yes | Cm no
211 is specified, host names are printed in
212 information displays.
215 is specified, numeric
216 addresses are printed instead.
220 modified using the command line
223 .It Ic keyid Ar keyid
224 This command allows the specification of a key number to be
225 used to authenticate configuration requests.
229 key number the server has been configured to use for this
233 .Cm OpenSSLDigestType
236 Specify the type of key to use for authenticating requests.
241 was built with OpenSSL support,
242 any digest type supported by OpenSSL can also be provided.
243 If no argument is given, the current
246 .It Ic ntpversion Xo Oo
253 Sets the NTP version number which
257 Defaults to 3, and note that mode 6 control messages (and
258 modes, for that matter) didn't exist in NTP version 1.
260 to be no servers left which demand version 1.
261 With no argument, displays the current NTP version that will be used
262 when communicating with servers.
264 This command prompts you to type in a password (which will not
265 be echoed) which will be used to authenticate configuration
267 The password must correspond to the key configured for
268 use by the NTP server for this purpose if such requests are to be
270 .\" Not yet implemented.
274 .\" Poll an NTP server in client mode
281 Causes all output from query commands is printed as received
282 from the remote server.
283 The only formating/interpretation done on
284 the data is to transform nonascii data into a printable (but barely
285 understandable) form.
286 .It Ic timeout Ar milliseconds
287 Specify a timeout period for responses to server queries.
289 default is about 5000 milliseconds.
292 retries each query once after a timeout, the total waiting time for
293 a timeout will be twice the timeout value set.
295 Print the version of the
299 .Ss "Control Message Commands"
300 Association IDs are used to identify system, peer and clock variables.
301 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.
302 Most control commands send a single mode\-6 message to the server and expect a single response message.
303 The exceptions are the
305 command, which sends a series of messages,
310 commands, which iterate over a range of associations.
311 .Bl -tag -width "something" -compact -offset indent
313 Display a list of mobilized associations in the form:
314 .Dl ind assid status conf reach auth condition last_event cnt
315 .Bl -column -offset indent ".Sy Variable" ".Sy Description"
316 .It Sy String Ta Sy Description
317 .It Li ind Ta index on this list
318 .It Li assid Ta association ID
319 .It Li status Ta peer status word
320 .It Li conf Ta Li yes : persistent, Li no : ephemeral
321 .It Li reach Ta Li yes : reachable, Li no : unreachable
322 .It Li auth Ta Li ok , Li yes , Li bad and Li none
323 .It Li condition Ta selection status (see the Li select field of the peer status word)
324 .It Li last_event Ta event report (see the Li event field of the peer status word)
325 .It Li cnt Ta event count (see the Li count field of the peer status word)
328 Display the authentication statistics.
329 .It Cm clockvar Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
330 .It Cm cv Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
331 Display a list of clock variables for those associations supporting a reference clock.
332 .It Cm :config Op ...
333 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.
334 .It Cm config\-from\-file Ar filename
335 Send the each line of
337 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.
339 Display statistics for each local network address. Authentication is required.
341 Display network and reference clock I/O statistics.
343 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.
345 Perform the same function as the associations command, except display mobilized and unmobilized associations.
351 Obtain and print a list of all peers and clients showing
353 (associated with any given IP version).
359 Print a peer spreadsheet for the appropriate IP version(s).
361 (associated with any given IP version).
363 Display monitor facility statistics.
364 .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
365 Obtain and print traffic counts collected and maintained by the monitor facility.
366 With the exception of
367 .Cm sort Ns = Ns Ar sortorder ,
368 the options filter the list returned by
374 options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
376 .Cm mincount Ns = Ns Ar count
377 option filters entries representing less than
381 .Cm laddr Ns = Ns Ar localaddr
382 option filters entries for packets received on any local address other than
384 .Cm resany Ns = Ns Ar hexmask
386 .Cm resall Ns = Ns Ar hexmask
387 filter entries containing none or less than all, respectively, of the bits in
389 which must begin with
400 or any of those preceded by a minus sign (hyphen) to reverse the sort order.
401 The output columns are:
402 .Bl -tag -width "something" -compact -offset indent
406 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
409 Average interval in s between packets from this address.
411 Restriction flags associated with this address.
412 Most are copied unchanged from the matching
414 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
416 Rate control indicator, either
421 for no rate control response,
422 rate limiting by discarding, or rate limiting with a KoD response, respectively.
426 Packet version number.
428 Packets received from this address.
430 Source port of last packet from this address.
431 .It Ic remote address
432 DNS name, numeric address, or address followed by
433 claimed DNS name which could not be verified in parentheses.
435 .It Ic mreadvar assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
436 .It Ic mrv assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
437 Perform the same function as the
439 command, except for a range of association IDs.
440 This range is determined from the association list cached by the most recent
448 Obtain and print the old\-style list of all peers and clients showing
450 (associated with any given IP version),
454 Perform the same function as the
457 except that it uses previously stored data rather than making a new query.
459 Display a list of peers in the form:
460 .Dl [tally]remote refid st t when pool reach delay offset jitter
461 .Bl -tag -width "something" -compact -offset indent
465 single\-character code indicating current value of the
468 .Lk decode.html#peer "peer status word"
470 host name (or IP number) of peer.
471 The value displayed will be truncated to 15 characters unless the
473 flag is given, in which case the full value will be displayed
475 and the remaining data is displayed on the next line.
478 .Lk decode.html#kiss "'kiss code"
483 unicast or manycast client,
485 broadcast or multicast client,
487 local (reference clock),
497 sec/min/hr since last received packet
499 poll interval (log2 s)
501 reach shift register (octal)
505 offset of server relative to this host
510 Display a list of peers in the form:
511 .Dl [tally]remote refid assid st t when pool reach delay offset jitter
512 where the output is just like the
514 command except that the
516 is displayed in hex format and the association number is also displayed.
517 .It Ic pstats Ar assocID
518 Show the statistics for the peer with the given
520 .It Ic readlist Ar assocID
522 Read the system or peer variables included in the variable list.
523 .It Ic readvar Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
524 .It Ic rv Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
525 Display the specified variables.
528 is zero, the variables are from the
530 name space, otherwise they are from the
535 is required, as the same name can occur in both spaces.
538 is included, all operative variables in the name space are displayed.
539 In this case only, if the
541 is omitted, it is assumed zero.
542 Multiple names are specified with comma separators and without whitespace.
543 Note that time values are represented in milliseconds
544 and frequency values in parts\-per\-million (PPM).
545 Some NTP timestamps are represented in the format
547 where YYYY is the year,
548 MM the month of year,
549 DD the day of month and
550 TTTT the time of day.
552 Show the access control (restrict) list for
554 .It Ic saveconfig Ar filename
555 Write the current configuration,
556 including any runtime modifications given with
559 .Ic config\-from\-file ,
560 to the ntpd host's file
562 This command will be rejected by the server unless
563 .Lk miscopt.html#saveconfigdir "saveconfigdir"
570 format specifies to substitute the current date and time, for example,
571 .Ic q]saveconfig ntp\-%Y%m%d\-%H%M%S.confq] .
572 The filename used is stored in system variable
574 Authentication is required.
576 Display interval timer counters.
577 .It Ic writelist Ar assocID
578 Write the system or peer variables included in the variable list.
579 .It Ic writevar Ar assocID Ar name Ns = Ns Ar value Op , ...
580 Write the specified variables.
583 is zero, the variables are from the
585 name space, otherwise they are from the
590 is required, as the same name can occur in both spaces.
592 Display operational summary.
594 Print statistics counters maintained in the protocol module.
596 .Ss Status Words and Kiss Codes
597 The current state of the operating program is shown
598 in a set of status words
599 maintained by the system.
600 Status information is also available on a per\-association basis.
601 These words are displayed in the
605 commands both in hexadecimal and in decoded short tip strings.
606 The codes, tips and short explanations are documented on the
607 .Lk decode.html "Event Messages and Status Words"
609 The page also includes a list of system and peer messages,
610 the code for the latest of which is included in the status word.
612 Information resulting from protocol machine state transitions
613 is displayed using an informal set of ASCII strings called
614 .Lk decode.html#kiss "kiss codes" .
615 The original purpose was for kiss\-o'\-death (KoD) packets
616 sent by the server to advise the client of an unusual condition.
617 They are now displayed, when appropriate,
618 in the reference identifier field in various billboards.
620 The following system variables appear in the
623 Not all variables are displayed in some configurations.
624 .Bl -tag -width "something" -compact -offset indent
628 .Lk decode.html#sys "system status word"
630 NTP software version and build time
632 hardware platform and version
634 operating system and version
636 leap warning indicator (0\-3)
642 total roundtrip delay to the primary reference clock
644 total dispersion to the primary reference clock
646 system peer association ID
648 time constant and poll exponent (log2 s) (3\-17)
650 minimum time constant (log2 s) (3\-10)
655 .Lk decode.html#kiss "kiss code"
659 combined offset of server relative to this host
661 combined system jitter
663 frequency offset (PPM) relative to hardware clock
665 clock frequency wander (PPM)
671 NTP seconds when the next leap second is/was inserted
673 NTP seconds when the NIST leapseconds file expires
675 The jitter and wander statistics are exponentially\-weighted RMS averages.
676 The system jitter is defined in the NTPv4 specification;
677 the clock jitter statistic is computed by the clock discipline module.
679 When the NTPv4 daemon is compiled with the OpenSSL software library,
680 additional system variables are displayed,
681 including some or all of the following,
682 depending on the particular Autokey dance:
683 .Bl -tag -width "something" -compact -offset indent
687 Autokey host name for this host
689 Autokey group name for this host
691 host flags (see Autokey specification)
693 OpenSSL message digest algorithm
695 OpenSSL digest/signature scheme
697 NTP seconds at last signature update
699 certificate subject, issuer and certificate flags
701 NTP seconds when the certificate expires
704 The following peer variables appear in the
706 billboard for each association.
707 Not all variables are displayed in some configurations.
708 .Bl -tag -width "something" -compact -offset indent
714 .Lk decode.html#peer "peer status word"
716 source (remote) IP address
720 destination (local) IP address
722 destination (local) port
724 leap indicator (0\-3)
730 total roundtrip delay to the primary reference clock
732 total root dispersion to the primary reference clock
735 .Lk decode.html#kiss "kiss code"
739 reach register (octal)
747 host poll exponent (log2 s) (3\-17)
749 peer poll exponent (log2 s) (3\-17)
752 .Lk rate.html "Rate Management and the Kiss\-o'\-Death Packet" )
754 .Lk decode.html#flash "flash status word"
764 Autokey group name for this association
766 unicast/broadcast bias
768 interleave delay (see
769 .Lk xleave.html "NTP Interleaved Modes" )
773 variable is calculated when the first broadcast packet is received
774 after the calibration volley.
775 It represents the offset of the broadcast subgraph relative to the unicast subgraph.
778 variable appears only for the interleaved symmetric and interleaved modes.
779 It represents the internal queuing, buffering and transmission delays
780 for the preceding packet.
782 When the NTPv4 daemon is compiled with the OpenSSL software library,
783 additional peer variables are displayed, including the following:
784 .Bl -tag -width "something" -compact -offset indent
788 peer flags (see Autokey specification)
792 peer flags (see Autokey specification)
794 OpenSSL digest/signature scheme
800 Autokey signature timestamp
803 The following clock variables appear in the
805 billboard for each association with a reference clock.
806 Not all variables are displayed in some configurations.
807 .Bl -tag -width "something" -compact -offset indent
813 .Lk decode.html#clock "clock status word"
817 ASCII time code string (specific to device)
840 Force IPv4 DNS name resolution.
841 This option must not appear in combination with any of the following options:
844 Force DNS resolution of following host names on the command line
845 to the IPv4 namespace.
847 Force IPv6 DNS name resolution.
848 This option must not appear in combination with any of the following options:
851 Force DNS resolution of following host names on the command line
852 to the IPv6 namespace.
853 .It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd
854 run a command and exit.
855 This option may appear an unlimited number of times.
857 The following argument is interpreted as an interactive format command
858 and is added to the list of commands to be executed on the specified
860 .It Fl d , Fl \-debug\-level
861 Increase debug verbosity level.
862 This option may appear an unlimited number of times.
864 .It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
865 Set the debug verbosity level.
866 This option may appear an unlimited number of times.
867 This option takes an integer number as its argument.
869 .It Fl i , Fl \-interactive
870 Force ntpq to operate in interactive mode.
871 This option must not appear in combination with any of the following options:
874 Force \fBntpq\fP to operate in interactive mode.
875 Prompts will be written to the standard output and
876 commands read from the standard input.
877 .It Fl n , Fl \-numeric
878 numeric host addresses.
880 Output all host addresses in dotted\-quad numeric format rather than
881 converting to the canonical host names.
883 Always output status line with readvar.
885 By default, \fBntpq\fP now suppresses the \fBassocid=...\fP
886 line that precedes the output of \fBreadvar\fP
887 (alias \fBrv\fP) when a single variable is requested, such as
888 \fBntpq \-c "rv 0 offset"\fP.
889 This option causes \fBntpq\fP to include both lines of output
890 for a single\-variable \fBreadvar\fP.
891 Using an environment variable to
892 preset this option in a script will enable both older and
893 newer \fBntpq\fP to behave identically in this regard.
894 .It Fl p , Fl \-peers
895 Print a list of the peers.
896 This option must not appear in combination with any of the following options:
899 Print a list of the peers known to the server as well as a summary
900 of their state. This is equivalent to the 'peers' interactive command.
901 .It Fl r Ar keyword , Fl \-refid Ns = Ns Ar keyword
902 Set default display type for S2+ refids.
903 This option takes a keyword as its argument. The argument sets an enumeration value that can
904 be tested by comparing them against the option value macro.
905 The available keywords are:
911 or their numeric equivalent.
920 Set the default display format for S2+ refids.
922 Display the full 'remote' value.
924 Display the full value of the 'remote' value. If this requires
925 more than 15 characters, display the full value, emit a newline,
926 and continue the data display properly indented on the next line.
927 .It Fl \&? , Fl \-help
928 Display usage information and exit.
929 .It Fl \&! , Fl \-more\-help
930 Pass the extended usage information through a pager.
931 .It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
932 Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP
933 configuration file listed in the \fBOPTION PRESETS\fP section, below.
934 The command will exit after updating the config file.
935 .It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
936 Load options from \fIcfgfile\fP.
937 The \fIno\-load\-opts\fP form will disable the loading
938 of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early,
940 .It Fl \-version Op Brq Ar v|c|n
941 Output version of program and exit. The default mode is `v', a simple
942 version. The `c' mode will print copyright information and `n' will
943 print the full copyright notice.
946 Any option that is not marked as \fInot presettable\fP may be preset
947 by loading values from configuration ("RC" or ".INI") file(s) and values from
948 environment variables named:
950 \fBNTPQ_<option\-name>\fP or \fBNTPQ\fP
953 The environmental presets take precedence (are processed later than)
954 the configuration files.
955 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
956 If any of these are directories, then the file \fI.ntprc\fP
957 is searched for within those directories.
959 See \fBOPTION PRESETS\fP for configuration environment variables.
961 See \fBOPTION PRESETS\fP for configuration files.
963 One of the following exit values will be returned:
965 .It 0 " (EXIT_SUCCESS)"
966 Successful program execution.
967 .It 1 " (EXIT_FAILURE)"
968 The operation failed or the command syntax was not valid.
969 .It 66 " (EX_NOINPUT)"
970 A specified configuration file could not be loaded.
971 .It 70 " (EX_SOFTWARE)"
972 libopts had an internal operational error. Please report
973 it to autogen\-users@lists.sourceforge.net. Thank you.
976 The University of Delaware and Network Time Foundation
978 Copyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved.
979 This program is released under the terms of the NTP license, <http://ntp.org/license>.
981 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
983 This manual page was \fIAutoGen\fP\-erated from the \fBntpq\fP
projects / FreeBSD / releng / 10.2.git / blob