2 .Dt NTPQ 8 User Commands
4 .\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc)
8 .\" It has been AutoGen-ed April 26, 2016 at 08:29:41 PM by AutoGen 5.18.5
9 .\" From the definitions ntpq-opts.def
10 .\" and the template file agmdoc-cmd.tpl
13 .Nd standard NTP query program
16 .\" Mixture of short (flag) options and long options
18 .Op Fl flag Op Ar value
19 .Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
25 utility program is used to query NTP servers which
26 implement the standard NTP mode 6 control message formats defined
27 in Appendix B of the NTPv3 specification RFC1305, requesting
28 information about current state and/or changes in that state.
29 The same formats are used in NTPv4, although some of the
30 variables have changed and new ones added. The description on this
31 page is for the NTPv4 variables.
32 The program may be run either in interactive mode or controlled using
33 command line arguments.
34 Requests to read and write arbitrary
35 variables can be assembled, with raw and pretty\-printed output
36 options being available.
39 utility can also obtain and print a
40 list of peers in a common format by sending multiple queries to the
42 If one or more request options is included on the command line
45 is executed, each of the requests will be sent
46 to the NTP servers running on each of the hosts given as command
47 line arguments, or on localhost by default.
51 will attempt to read commands from the
52 standard input and execute these on the NTP server running on the
53 first host given on the command line, again defaulting to localhost
54 when no other host is specified.
57 utility will prompt for
58 commands if the standard input is a terminal device.
60 uses NTP mode 6 packets to communicate with the
61 NTP server, and hence can be used to query any compatible server on
62 the network which permits it.
63 Note that since NTP is a UDP protocol
64 this communication will be somewhat unreliable, especially over
65 large distances in terms of network topology.
69 one attempt to retransmit requests, and will time requests out if
70 the remote host is not heard from within a suitable timeout
73 command line option other than
78 cause the specified query (queries) to be sent to the indicated
83 interactive format commands from the standard input.
84 .Ss "Internal Commands"
85 Interactive format commands consist of a keyword followed by zero
87 Only enough characters of the full keyword to
88 uniquely identify the command need be typed.
90 number of interactive format commands are executed entirely within
93 utility itself and do not result in NTP mode 6
94 requests being sent to a server.
95 These are described following.
96 .Bl -tag -width "? [command_keyword]" -compact -offset indent
97 .It Ic ? Op Ar command_keyword
98 .It Ic help Op Ar command_keyword
101 by itself will print a list of all the command
102 keywords known to this incarnation of
106 followed by a command keyword will print function and usage
107 information about the command.
108 This command is probably a better
109 source of information about
113 .It Ic addvars Ar variable_name Ns Xo Op Ic =value
116 .It Ic rmvars Ar variable_name Ic ...
119 The data carried by NTP mode 6 messages consists of a list of
121 .Ql variable_name=value ,
124 is ignored, and can be omitted,
125 in requests to the server to read variables.
128 utility maintains an internal list in which data to be included in control
129 messages can be assembled, and sent using the
133 commands described below.
136 command allows variables and their optional values to be added to
138 If more than one variable is to be added, the list should
139 be comma\-separated and not contain white space.
142 command can be used to remove individual variables from the list,
145 command removes all variables from the
149 command displays the current list of optional variables.
150 .It Ic authenticate Op yes | no
153 does not authenticate requests unless
154 they are write requests.
159 to send authentication with all requests it
161 Authenticated requests causes some servers to handle
162 requests slightly differently, and can occasionally melt the CPU in
163 fuzzballs if you turn authentication on before doing a
170 to display whether or not
172 is currently autheinticating requests.
174 Causes output from query commands to be "cooked", so that
175 variables which are recognized by
178 values reformatted for human consumption.
181 thinks should have a decodable value but didn't are
182 marked with a trailing
192 With no argument, displays the current debug level.
193 Otherwise, the debug level is changed to the indicated level.
194 .It Ic delay Ar milliseconds
195 Specify a time interval to be added to timestamps included in
196 requests which require authentication.
197 This is used to enable
198 (unreliable) server reconfiguration over long delay network paths
199 or between machines whose clocks are unsynchronized.
201 server does not now require timestamps in authenticated requests,
202 so this command may be obsolete.
206 .It Ic host Ar hostname
207 Set the host to which future queries will be sent.
209 may be either a host name or a numeric address.
210 .It Ic hostnames Op Cm yes | Cm no
213 is specified, host names are printed in
214 information displays.
217 is specified, numeric
218 addresses are printed instead.
222 modified using the command line
225 .It Ic keyid Ar keyid
226 This command allows the specification of a key number to be
227 used to authenticate configuration requests.
231 key number the server has been configured to use for this
235 .Cm OpenSSLDigestType
238 Specify the type of key to use for authenticating requests.
243 was built with OpenSSL support,
244 any digest type supported by OpenSSL can also be provided.
245 If no argument is given, the current
248 .It Ic ntpversion Xo Oo
255 Sets the NTP version number which
259 Defaults to 3, and note that mode 6 control messages (and
260 modes, for that matter) didn't exist in NTP version 1.
262 to be no servers left which demand version 1.
263 With no argument, displays the current NTP version that will be used
264 when communicating with servers.
266 This command prompts you to type in a password (which will not
267 be echoed) which will be used to authenticate configuration
269 The password must correspond to the key configured for
270 use by the NTP server for this purpose if such requests are to be
272 .\" Not yet implemented.
276 .\" Poll an NTP server in client mode
283 Causes all output from query commands is printed as received
284 from the remote server.
285 The only formating/interpretation done on
286 the data is to transform nonascii data into a printable (but barely
287 understandable) form.
288 .It Ic timeout Ar milliseconds
289 Specify a timeout period for responses to server queries.
291 default is about 5000 milliseconds.
294 retries each query once after a timeout, the total waiting time for
295 a timeout will be twice the timeout value set.
297 Print the version of the
301 .Ss "Control Message Commands"
302 Association IDs are used to identify system, peer and clock variables.
303 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.
304 Most control commands send a single mode\-6 message to the server and expect a single response message.
305 The exceptions are the
307 command, which sends a series of messages,
312 commands, which iterate over a range of associations.
313 .Bl -tag -width "something" -compact -offset indent
315 Display a list of mobilized associations in the form:
316 .Dl ind assid status conf reach auth condition last_event cnt
317 .Bl -column -offset indent ".Sy Variable" ".Sy Description"
318 .It Sy String Ta Sy Description
319 .It Li ind Ta index on this list
320 .It Li assid Ta association ID
321 .It Li status Ta peer status word
322 .It Li conf Ta Li yes : persistent, Li no : ephemeral
323 .It Li reach Ta Li yes : reachable, Li no : unreachable
324 .It Li auth Ta Li ok , Li yes , Li bad and Li none
325 .It Li condition Ta selection status (see the Li select field of the peer status word)
326 .It Li last_event Ta event report (see the Li event field of the peer status word)
327 .It Li cnt Ta event count (see the Li count field of the peer status word)
330 Display the authentication statistics.
331 .It Cm clockvar Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
332 .It Cm cv Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
333 Display a list of clock variables for those associations supporting a reference clock.
334 .It Cm :config Op ...
335 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.
336 .It Cm config\-from\-file Ar filename
337 Send the each line of
339 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.
341 Display statistics for each local network address. Authentication is required.
343 Display network and reference clock I/O statistics.
345 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.
347 Perform the same function as the associations command, except display mobilized and unmobilized associations.
353 Obtain and print a list of all peers and clients showing
355 (associated with any given IP version).
361 Print a peer spreadsheet for the appropriate IP version(s).
363 (associated with any given IP version).
365 Display monitor facility statistics.
366 .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
367 Obtain and print traffic counts collected and maintained by the monitor facility.
368 With the exception of
369 .Cm sort Ns = Ns Ar sortorder ,
370 the options filter the list returned by
376 options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
378 .Cm mincount Ns = Ns Ar count
379 option filters entries representing less than
383 .Cm laddr Ns = Ns Ar localaddr
384 option filters entries for packets received on any local address other than
386 .Cm resany Ns = Ns Ar hexmask
388 .Cm resall Ns = Ns Ar hexmask
389 filter entries containing none or less than all, respectively, of the bits in
391 which must begin with
402 or any of those preceded by a minus sign (hyphen) to reverse the sort order.
403 The output columns are:
404 .Bl -tag -width "something" -compact -offset indent
408 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
411 Average interval in s between packets from this address.
413 Restriction flags associated with this address.
414 Most are copied unchanged from the matching
416 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
418 Rate control indicator, either
423 for no rate control response,
424 rate limiting by discarding, or rate limiting with a KoD response, respectively.
428 Packet version number.
430 Packets received from this address.
432 Source port of last packet from this address.
433 .It Ic remote address
434 DNS name, numeric address, or address followed by
435 claimed DNS name which could not be verified in parentheses.
437 .It Ic mreadvar assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
438 .It Ic mrv assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
439 Perform the same function as the
441 command, except for a range of association IDs.
442 This range is determined from the association list cached by the most recent
450 Obtain and print the old\-style list of all peers and clients showing
452 (associated with any given IP version),
456 Perform the same function as the
459 except that it uses previously stored data rather than making a new query.
461 Display a list of peers in the form:
462 .Dl [tally]remote refid st t when pool reach delay offset jitter
463 .Bl -tag -width "something" -compact -offset indent
467 single\-character code indicating current value of the
470 .Lk decode.html#peer "peer status word"
472 host name (or IP number) of peer.
473 The value displayed will be truncated to 15 characters unless the
475 flag is given, in which case the full value will be displayed
477 and the remaining data is displayed on the next line.
480 .Lk decode.html#kiss "'kiss code"
485 unicast or manycast client,
487 broadcast or multicast client,
489 local (reference clock),
499 sec/min/hr since last received packet
501 poll interval (log2 s)
503 reach shift register (octal)
507 offset of server relative to this host
512 Display a list of peers in the form:
513 .Dl [tally]remote refid assid st t when pool reach delay offset jitter
514 where the output is just like the
516 command except that the
518 is displayed in hex format and the association number is also displayed.
519 .It Ic pstats Ar assocID
520 Show the statistics for the peer with the given
522 .It Ic readlist Ar assocID
524 Read the system or peer variables included in the variable list.
525 .It Ic readvar Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
526 .It Ic rv Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
527 Display the specified variables.
530 is zero, the variables are from the
532 name space, otherwise they are from the
537 is required, as the same name can occur in both spaces.
540 is included, all operative variables in the name space are displayed.
541 In this case only, if the
543 is omitted, it is assumed zero.
544 Multiple names are specified with comma separators and without whitespace.
545 Note that time values are represented in milliseconds
546 and frequency values in parts\-per\-million (PPM).
547 Some NTP timestamps are represented in the format
549 where YYYY is the year,
550 MM the month of year,
551 DD the day of month and
552 TTTT the time of day.
554 Show the access control (restrict) list for
556 .It Ic saveconfig Ar filename
557 Write the current configuration,
558 including any runtime modifications given with
561 .Ic config\-from\-file ,
562 to the ntpd host's file
564 This command will be rejected by the server unless
565 .Lk miscopt.html#saveconfigdir "saveconfigdir"
572 format specifies to substitute the current date and time, for example,
573 .Ic q]saveconfig ntp\-%Y%m%d\-%H%M%S.confq] .
574 The filename used is stored in system variable
576 Authentication is required.
578 Display interval timer counters.
579 .It Ic writelist Ar assocID
580 Write the system or peer variables included in the variable list.
581 .It Ic writevar Ar assocID Ar name Ns = Ns Ar value Op , ...
582 Write the specified variables.
585 is zero, the variables are from the
587 name space, otherwise they are from the
592 is required, as the same name can occur in both spaces.
594 Display operational summary.
596 Print statistics counters maintained in the protocol module.
598 .Ss Status Words and Kiss Codes
599 The current state of the operating program is shown
600 in a set of status words
601 maintained by the system.
602 Status information is also available on a per\-association basis.
603 These words are displayed in the
607 commands both in hexadecimal and in decoded short tip strings.
608 The codes, tips and short explanations are documented on the
609 .Lk decode.html "Event Messages and Status Words"
611 The page also includes a list of system and peer messages,
612 the code for the latest of which is included in the status word.
614 Information resulting from protocol machine state transitions
615 is displayed using an informal set of ASCII strings called
616 .Lk decode.html#kiss "kiss codes" .
617 The original purpose was for kiss\-o'\-death (KoD) packets
618 sent by the server to advise the client of an unusual condition.
619 They are now displayed, when appropriate,
620 in the reference identifier field in various billboards.
622 The following system variables appear in the
625 Not all variables are displayed in some configurations.
626 .Bl -tag -width "something" -compact -offset indent
630 .Lk decode.html#sys "system status word"
632 NTP software version and build time
634 hardware platform and version
636 operating system and version
638 leap warning indicator (0\-3)
644 total roundtrip delay to the primary reference clock
646 total dispersion to the primary reference clock
648 system peer association ID
650 time constant and poll exponent (log2 s) (3\-17)
652 minimum time constant (log2 s) (3\-10)
657 .Lk decode.html#kiss "kiss code"
661 combined offset of server relative to this host
663 combined system jitter
665 frequency offset (PPM) relative to hardware clock
667 clock frequency wander (PPM)
673 NTP seconds when the next leap second is/was inserted
675 NTP seconds when the NIST leapseconds file expires
677 The jitter and wander statistics are exponentially\-weighted RMS averages.
678 The system jitter is defined in the NTPv4 specification;
679 the clock jitter statistic is computed by the clock discipline module.
681 When the NTPv4 daemon is compiled with the OpenSSL software library,
682 additional system variables are displayed,
683 including some or all of the following,
684 depending on the particular Autokey dance:
685 .Bl -tag -width "something" -compact -offset indent
689 Autokey host name for this host
691 Autokey group name for this host
693 host flags (see Autokey specification)
695 OpenSSL message digest algorithm
697 OpenSSL digest/signature scheme
699 NTP seconds at last signature update
701 certificate subject, issuer and certificate flags
703 NTP seconds when the certificate expires
706 The following peer variables appear in the
708 billboard for each association.
709 Not all variables are displayed in some configurations.
710 .Bl -tag -width "something" -compact -offset indent
716 .Lk decode.html#peer "peer status word"
718 source (remote) IP address
722 destination (local) IP address
724 destination (local) port
726 leap indicator (0\-3)
732 total roundtrip delay to the primary reference clock
734 total root dispersion to the primary reference clock
737 .Lk decode.html#kiss "kiss code"
741 reach register (octal)
749 host poll exponent (log2 s) (3\-17)
751 peer poll exponent (log2 s) (3\-17)
754 .Lk rate.html "Rate Management and the Kiss\-o'\-Death Packet" )
756 .Lk decode.html#flash "flash status word"
766 Autokey group name for this association
768 unicast/broadcast bias
770 interleave delay (see
771 .Lk xleave.html "NTP Interleaved Modes" )
775 variable is calculated when the first broadcast packet is received
776 after the calibration volley.
777 It represents the offset of the broadcast subgraph relative to the unicast subgraph.
780 variable appears only for the interleaved symmetric and interleaved modes.
781 It represents the internal queuing, buffering and transmission delays
782 for the preceding packet.
784 When the NTPv4 daemon is compiled with the OpenSSL software library,
785 additional peer variables are displayed, including the following:
786 .Bl -tag -width "something" -compact -offset indent
790 peer flags (see Autokey specification)
794 peer flags (see Autokey specification)
796 OpenSSL digest/signature scheme
802 Autokey signature timestamp
805 The following clock variables appear in the
807 billboard for each association with a reference clock.
808 Not all variables are displayed in some configurations.
809 .Bl -tag -width "something" -compact -offset indent
815 .Lk decode.html#clock "clock status word"
819 ASCII time code string (specific to device)
842 Force IPv4 DNS name resolution.
843 This option must not appear in combination with any of the following options:
846 Force DNS resolution of following host names on the command line
847 to the IPv4 namespace.
849 Force IPv6 DNS name resolution.
850 This option must not appear in combination with any of the following options:
853 Force DNS resolution of following host names on the command line
854 to the IPv6 namespace.
855 .It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd
856 run a command and exit.
857 This option may appear an unlimited number of times.
859 The following argument is interpreted as an interactive format command
860 and is added to the list of commands to be executed on the specified
862 .It Fl d , Fl \-debug\-level
863 Increase debug verbosity level.
864 This option may appear an unlimited number of times.
866 .It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
867 Set the debug verbosity level.
868 This option may appear an unlimited number of times.
869 This option takes an integer number as its argument.
871 .It Fl i , Fl \-interactive
872 Force ntpq to operate in interactive mode.
873 This option must not appear in combination with any of the following options:
876 Force \fBntpq\fP to operate in interactive mode.
877 Prompts will be written to the standard output and
878 commands read from the standard input.
879 .It Fl n , Fl \-numeric
880 numeric host addresses.
882 Output all host addresses in dotted\-quad numeric format rather than
883 converting to the canonical host names.
885 Always output status line with readvar.
887 By default, \fBntpq\fP now suppresses the \fBassocid=...\fP
888 line that precedes the output of \fBreadvar\fP
889 (alias \fBrv\fP) when a single variable is requested, such as
890 \fBntpq \-c "rv 0 offset"\fP.
891 This option causes \fBntpq\fP to include both lines of output
892 for a single\-variable \fBreadvar\fP.
893 Using an environment variable to
894 preset this option in a script will enable both older and
895 newer \fBntpq\fP to behave identically in this regard.
896 .It Fl p , Fl \-peers
897 Print a list of the peers.
898 This option must not appear in combination with any of the following options:
901 Print a list of the peers known to the server as well as a summary
902 of their state. This is equivalent to the 'peers' interactive command.
903 .It Fl r Ar keyword , Fl \-refid Ns = Ns Ar keyword
904 Set default display type for S2+ refids.
905 This option takes a keyword as its argument. The argument sets an enumeration value that can
906 be tested by comparing them against the option value macro.
907 The available keywords are:
913 or their numeric equivalent.
922 Set the default display format for S2+ refids.
924 Display the full 'remote' value.
926 Display the full value of the 'remote' value. If this requires
927 more than 15 characters, display the full value, emit a newline,
928 and continue the data display properly indented on the next line.
929 .It Fl \&? , Fl \-help
930 Display usage information and exit.
931 .It Fl \&! , Fl \-more\-help
932 Pass the extended usage information through a pager.
933 .It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
934 Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP
935 configuration file listed in the \fBOPTION PRESETS\fP section, below.
936 The command will exit after updating the config file.
937 .It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
938 Load options from \fIcfgfile\fP.
939 The \fIno\-load\-opts\fP form will disable the loading
940 of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early,
942 .It Fl \-version Op Brq Ar v|c|n
943 Output version of program and exit. The default mode is `v', a simple
944 version. The `c' mode will print copyright information and `n' will
945 print the full copyright notice.
948 Any option that is not marked as \fInot presettable\fP may be preset
949 by loading values from configuration ("RC" or ".INI") file(s) and values from
950 environment variables named:
952 \fBNTPQ_<option\-name>\fP or \fBNTPQ\fP
955 The environmental presets take precedence (are processed later than)
956 the configuration files.
957 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
958 If any of these are directories, then the file \fI.ntprc\fP
959 is searched for within those directories.
961 See \fBOPTION PRESETS\fP for configuration environment variables.
963 See \fBOPTION PRESETS\fP for configuration files.
965 One of the following exit values will be returned:
967 .It 0 " (EXIT_SUCCESS)"
968 Successful program execution.
969 .It 1 " (EXIT_FAILURE)"
970 The operation failed or the command syntax was not valid.
971 .It 66 " (EX_NOINPUT)"
972 A specified configuration file could not be loaded.
973 .It 70 " (EX_SOFTWARE)"
974 libopts had an internal operational error. Please report
975 it to autogen\-users@lists.sourceforge.net. Thank you.
978 The University of Delaware and Network Time Foundation
980 Copyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved.
981 This program is released under the terms of the NTP license, <http://ntp.org/license>.
983 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
985 This manual page was \fIAutoGen\fP\-erated from the \fBntpq\fP
projects / FreeBSD / releng / 10.2.git / blob