2 .Dt NTPQ @NTPQ_MS@ User Commands
4 .\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc)
6 .\" It has been AutoGen-ed April 7, 2015 at 04:27:09 AM by AutoGen 5.18.5pre4
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.
227 to a key number the server has been configured to use for this
231 .Cm OpenSSLDigestType
234 Specify the type of key to use for authenticating requests.
239 was built with OpenSSL support,
240 any digest type supported by OpenSSL can also be provided.
241 If no argument is given, the current
244 .It Ic ntpversion Xo Oo
251 Sets the NTP version number which
255 Defaults to 3, and note that mode 6 control messages (and
256 modes, for that matter) didn't exist in NTP version 1.
258 to be no servers left which demand version 1.
259 With no argument, displays the current NTP version that will be used
260 when communicating with servers.
262 This command prompts you to type in a password (which will not
263 be echoed) which will be used to authenticate configuration
265 The password must correspond to the key configured for
266 use by the NTP server for this purpose if such requests are to be
268 .\" Not yet implemented.
272 .\" Poll an NTP server in client mode
279 Causes all output from query commands is printed as received
280 from the remote server.
281 The only formating/interpretation done on
282 the data is to transform nonascii data into a printable (but barely
283 understandable) form.
284 .It Ic timeout Ar milliseconds
285 Specify a timeout period for responses to server queries.
287 default is about 5000 milliseconds.
290 retries each query once after a timeout, the total waiting time for
291 a timeout will be twice the timeout value set.
293 Print the version of the
297 .Ss "Control Message Commands"
298 Association IDs are used to identify system, peer and clock variables.
299 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.
300 Most control commands send a single mode\-6 message to the server and expect a single response message.
301 The exceptions are the
303 command, which sends a series of messages,
308 commands, which iterate over a range of associations.
309 .Bl -tag -width "something" -compact -offset indent
311 Display a list of mobilized associations in the form:
312 .Dl ind assid status conf reach auth condition last_event cnt
313 .Bl -column -offset indent ".Sy Variable" ".Sy Description"
314 .It Sy String Ta Sy Description
315 .It Li ind Ta index on this list
316 .It Li assid Ta association ID
317 .It Li status Ta peer status word
318 .It Li conf Ta Li yes : persistent, Li no : ephemeral
319 .It Li reach Ta Li yes : reachable, Li no : unreachable
320 .It Li auth Ta Li ok , Li yes , Li bad and Li none
321 .It Li condition Ta selection status (see the Li select field of the peer status word)
322 .It Li last_event Ta event report (see the Li event field of the peer status word)
323 .It Li cnt Ta event count (see the Li count field of the peer status word)
326 Display the authentication statistics.
327 .It Cm clockvar Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
328 .It Cm cv Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ...
329 Display a list of clock variables for those associations supporting a reference clock.
330 .It Cm :config Op ...
331 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.
332 .It Cm config\-from\-file Ar filename
333 Send the each line of
335 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.
337 Display statistics for each local network address. Authentication is required.
339 Display network and reference clock I/O statistics.
341 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.
343 Perform the same function as the associations command, except display mobilized and unmobilized associations.
349 Obtain and print a list of all peers and clients showing
351 (associated with any given IP version).
357 Print a peer spreadsheet for the appropriate IP version(s).
359 (associated with any given IP version).
361 Display monitor facility statistics.
362 .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
363 Obtain and print traffic counts collected and maintained by the monitor facility.
364 With the exception of
365 .Cm sort Ns = Ns Ar sortorder ,
366 the options filter the list returned by
372 options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
374 .Cm mincount Ns = Ns Ar count
375 option filters entries representing less than
379 .Cm laddr Ns = Ns Ar localaddr
380 option filters entries for packets received on any local address other than
382 .Cm resany Ns = Ns Ar hexmask
384 .Cm resall Ns = Ns Ar hexmask
385 filter entries containing none or less than all, respectively, of the bits in
387 which must begin with
398 or any of those preceded by a minus sign (hyphen) to reverse the sort order.
399 The output columns are:
400 .Bl -tag -width "something" -compact -offset indent
404 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
407 Average interval in s between packets from this address.
409 Restriction flags associated with this address.
410 Most are copied unchanged from the matching
412 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
414 Rate control indicator, either
419 for no rate control response,
420 rate limiting by discarding, or rate limiting with a KoD response, respectively.
424 Packet version number.
426 Packets received from this address.
428 Source port of last packet from this address.
429 .It Ic remote address
430 DNS name, numeric address, or address followed by
431 claimed DNS name which could not be verified in parentheses.
433 .It Ic mreadvar assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
434 .It Ic mrv assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ...
435 Perform the same function as the
437 command, except for a range of association IDs.
438 This range is determined from the association list cached by the most recent
446 Obtain and print the old\-style list of all peers and clients showing
448 (associated with any given IP version),
452 Perform the same function as the
455 except that it uses previously stored data rather than making a new query.
457 Display a list of peers in the form:
458 .Dl [tally]remote refid st t when pool reach delay offset jitter
459 .Bl -tag -width "something" -compact -offset indent
463 single\-character code indicating current value of the
466 .Lk decode.html#peer "peer status word"
468 host name (or IP number) of peer.
469 The value displayed will be truncated to 15 characters unless the
471 flag is given, in which case the full value will be displayed
473 and the remaining data is displayed on the next line.
476 .Lk decode.html#kiss "'kiss code"
481 unicast or manycast client,
483 broadcast or multicast client,
485 local (reference clock),
495 sec/min/hr since last received packet
497 poll interval (log2 s)
499 reach shift register (octal)
503 offset of server relative to this host
507 .It Ic pstats Ar assocID
508 Show the statistics for the peer with the given
510 .It Ic readlist Ar assocID
512 Read the system or peer variables included in the variable list.
513 .It Ic readvar Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
514 .It Ic rv Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc
515 Display the specified variables.
518 is zero, the variables are from the
520 name space, otherwise they are from the
525 is required, as the same name can occur in both spaces.
528 is included, all operative variables in the name space are displayed.
529 In this case only, if the
531 is omitted, it is assumed zero.
532 Multiple names are specified with comma separators and without whitespace.
533 Note that time values are represented in milliseconds
534 and frequency values in parts\-per\-million (PPM).
535 Some NTP timestamps are represented in the format
537 where YYYY is the year,
538 MM the month of year,
539 DD the day of month and
540 TTTT the time of day.
542 Show the access control (restrict) list for
544 .It Ic saveconfig Ar filename
545 Write the current configuration,
546 including any runtime modifications given with
549 .Ic config\-from\-file ,
550 to the ntpd host's file
552 This command will be rejected by the server unless
553 .Lk miscopt.html#saveconfigdir "saveconfigdir"
560 format specifies to substitute the current date and time, for example,
561 .Ic q]saveconfig ntp\-%Y%m%d\-%H%M%S.confq] .
562 The filename used is stored in system variable
564 Authentication is required.
566 Display interval timer counters.
567 .It Ic writelist Ar assocID
568 Write the system or peer variables included in the variable list.
569 .It Ic writevar Ar assocID Ar name Ns = Ns Ar value Op , ...
570 Write the specified variables.
573 is zero, the variables are from the
575 name space, otherwise they are from the
580 is required, as the same name can occur in both spaces.
582 Display operational summary.
584 Print statistics counters maintained in the protocol module.
586 .Ss Status Words and Kiss Codes
587 The current state of the operating program is shown
588 in a set of status words
589 maintained by the system.
590 Status information is also available on a per\-association basis.
591 These words are displayed in the
595 commands both in hexadecimal and in decoded short tip strings.
596 The codes, tips and short explanations are documented on the
597 .Lk decode.html "Event Messages and Status Words"
599 The page also includes a list of system and peer messages,
600 the code for the latest of which is included in the status word.
602 Information resulting from protocol machine state transitions
603 is displayed using an informal set of ASCII strings called
604 .Lk decode.html#kiss "kiss codes" .
605 The original purpose was for kiss\-o'\-death (KoD) packets
606 sent by the server to advise the client of an unusual condition.
607 They are now displayed, when appropriate,
608 in the reference identifier field in various billboards.
610 The following system variables appear in the
613 Not all variables are displayed in some configurations.
614 .Bl -tag -width "something" -compact -offset indent
618 .Lk decode.html#sys "system status word"
620 NTP software version and build time
622 hardware platform and version
624 operating system and version
626 leap warning indicator (0\-3)
632 total roundtrip delay to the primary reference clock
634 total dispersion to the primary reference clock
636 system peer association ID
638 time constant and poll exponent (log2 s) (3\-17)
640 minimum time constant (log2 s) (3\-10)
645 .Lk decode.html#kiss "kiss code"
649 combined offset of server relative to this host
651 combined system jitter
653 frequency offset (PPM) relative to hardware clock
655 clock frequency wander (PPM)
661 NTP seconds when the next leap second is/was inserted
663 NTP seconds when the NIST leapseconds file expires
665 The jitter and wander statistics are exponentially\-weighted RMS averages.
666 The system jitter is defined in the NTPv4 specification;
667 the clock jitter statistic is computed by the clock discipline module.
669 When the NTPv4 daemon is compiled with the OpenSSL software library,
670 additional system variables are displayed,
671 including some or all of the following,
672 depending on the particular Autokey dance:
673 .Bl -tag -width "something" -compact -offset indent
677 Autokey host name for this host
679 Autokey group name for this host
681 host flags (see Autokey specification)
683 OpenSSL message digest algorithm
685 OpenSSL digest/signature scheme
687 NTP seconds at last signature update
689 certificate subject, issuer and certificate flags
691 NTP seconds when the certificate expires
694 The following peer variables appear in the
696 billboard for each association.
697 Not all variables are displayed in some configurations.
698 .Bl -tag -width "something" -compact -offset indent
704 .Lk decode.html#peer "peer status word"
706 source (remote) IP address
710 destination (local) IP address
712 destination (local) port
714 leap indicator (0\-3)
720 total roundtrip delay to the primary reference clock
722 total root dispersion to the primary reference clock
725 .Lk decode.html#kiss "kiss code"
729 reach register (octal)
737 host poll exponent (log2 s) (3\-17)
739 peer poll exponent (log2 s) (3\-17)
742 .Lk rate.html "Rate Management and the Kiss\-o'\-Death Packet" )
744 .Lk decode.html#flash "flash status word"
754 Autokey group name for this association
756 unicast/broadcast bias
758 interleave delay (see
759 .Lk xleave.html "NTP Interleaved Modes" )
763 variable is calculated when the first broadcast packet is received
764 after the calibration volley.
765 It represents the offset of the broadcast subgraph relative to the unicast subgraph.
768 variable appears only for the interleaved symmetric and interleaved modes.
769 It represents the internal queuing, buffering and transmission delays
770 for the preceding packet.
772 When the NTPv4 daemon is compiled with the OpenSSL software library,
773 additional peer variables are displayed, including the following:
774 .Bl -tag -width "something" -compact -offset indent
778 peer flags (see Autokey specification)
782 peer flags (see Autokey specification)
784 OpenSSL digest/signature scheme
790 Autokey signature timestamp
793 The following clock variables appear in the
795 billboard for each association with a reference clock.
796 Not all variables are displayed in some configurations.
797 .Bl -tag -width "something" -compact -offset indent
803 .Lk decode.html#clock "clock status word"
807 ASCII time code string (specific to device)
830 Force IPv4 DNS name resolution.
831 This option must not appear in combination with any of the following options:
834 Force DNS resolution of following host names on the command line
835 to the IPv4 namespace.
837 Force IPv6 DNS name resolution.
838 This option must not appear in combination with any of the following options:
841 Force DNS resolution of following host names on the command line
842 to the IPv6 namespace.
843 .It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd
844 run a command and exit.
845 This option may appear an unlimited number of times.
847 The following argument is interpreted as an interactive format command
848 and is added to the list of commands to be executed on the specified
850 .It Fl d , Fl \-debug\-level
851 Increase debug verbosity level.
852 This option may appear an unlimited number of times.
854 .It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
855 Set the debug verbosity level.
856 This option may appear an unlimited number of times.
857 This option takes an integer number as its argument.
859 .It Fl i , Fl \-interactive
860 Force ntpq to operate in interactive mode.
861 This option must not appear in combination with any of the following options:
864 Force \fBntpq\fP to operate in interactive mode.
865 Prompts will be written to the standard output and
866 commands read from the standard input.
867 .It Fl n , Fl \-numeric
868 numeric host addresses.
870 Output all host addresses in dotted\-quad numeric format rather than
871 converting to the canonical host names.
873 Always output status line with readvar.
875 By default, \fBntpq\fP now suppresses the \fBassocid=...\fP
876 line that precedes the output of \fBreadvar\fP
877 (alias \fBrv\fP) when a single variable is requested, such as
878 \fBntpq \-c "rv 0 offset"\fP.
879 This option causes \fBntpq\fP to include both lines of output
880 for a single\-variable \fBreadvar\fP.
881 Using an environment variable to
882 preset this option in a script will enable both older and
883 newer \fBntpq\fP to behave identically in this regard.
884 .It Fl p , Fl \-peers
885 Print a list of the peers.
886 This option must not appear in combination with any of the following options:
889 Print a list of the peers known to the server as well as a summary
890 of their state. This is equivalent to the 'peers' interactive command.
892 Display the full 'remote' value.
894 Display the full value of the 'remote' value. If this requires
895 more than 15 characters, display the full value, emit a newline,
896 and continue the data display properly indented on the next line.
897 .It Fl \&? , Fl \-help
898 Display usage information and exit.
899 .It Fl \&! , Fl \-more\-help
900 Pass the extended usage information through a pager.
901 .It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
902 Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP
903 configuration file listed in the \fBOPTION PRESETS\fP section, below.
904 The command will exit after updating the config file.
905 .It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
906 Load options from \fIcfgfile\fP.
907 The \fIno\-load\-opts\fP form will disable the loading
908 of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early,
910 .It Fl \-version Op Brq Ar v|c|n
911 Output version of program and exit. The default mode is `v', a simple
912 version. The `c' mode will print copyright information and `n' will
913 print the full copyright notice.
916 Any option that is not marked as \fInot presettable\fP may be preset
917 by loading values from configuration ("RC" or ".INI") file(s) and values from
918 environment variables named:
920 \fBNTPQ_<option\-name>\fP or \fBNTPQ\fP
923 The environmental presets take precedence (are processed later than)
924 the configuration files.
925 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
926 If any of these are directories, then the file \fI.ntprc\fP
927 is searched for within those directories.
929 See \fBOPTION PRESETS\fP for configuration environment variables.
931 See \fBOPTION PRESETS\fP for configuration files.
933 One of the following exit values will be returned:
935 .It 0 " (EXIT_SUCCESS)"
936 Successful program execution.
937 .It 1 " (EXIT_FAILURE)"
938 The operation failed or the command syntax was not valid.
939 .It 66 " (EX_NOINPUT)"
940 A specified configuration file could not be loaded.
941 .It 70 " (EX_SOFTWARE)"
942 libopts had an internal operational error. Please report
943 it to autogen\-users@lists.sourceforge.net. Thank you.
946 The University of Delaware and Network Time Foundation
948 Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved.
949 This program is released under the terms of the NTP license, <http://ntp.org/license>.
951 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
953 This manual page was \fIAutoGen\fP\-erated from the \fBntpq\fP
projects / FreeBSD / FreeBSD.git / blob