2 .\" $FreeBSD: src/usr.sbin/ntp/doc/ntpq.8,v 1.3.2.9 2003/03/11 22:31:30 trhodes Exp $
3 .\" $DragonFly: src/usr.sbin/ntp/doc/Attic/ntpq.8,v 1.2 2003/06/17 04:29:58 dillon Exp $
10 .Nd standard NTP query program
19 utility is used to query NTP servers
20 which implement the recommended NTP mode 6 control message format
21 about current state and to request changes in that state.
23 program may be run either in interactive mode or controlled using
24 command line arguments.
25 Requests to read and write arbitrary
26 variables can be assembled, with raw and pretty-printed output
27 options being available.
30 utility can also obtain and print a
31 list of peers in a common format by sending multiple queries to the
34 If one or more request options is included on the command line
37 is executed, each of the requests will be sent
38 to the NTP servers running on each of the hosts given as command
39 line arguments, or on localhost by default.
43 will attempt to read commands from the
44 standard input and execute these on the NTP server running on the
45 first host given on the command line, again defaulting to localhost
46 when no other host is specified.
49 utility will prompt for
50 commands if the standard input is a terminal device.
54 utility uses NTP mode 6 packets to communicate with the
55 NTP server, and hence can be used to query any compatible server on
56 the network which permits it.
57 Note that since NTP is a UDP protocol
58 this communication will be somewhat unreliable, especially over
59 large distances in terms of network topology.
63 one attempt to retransmit requests, and will time requests out if
64 the remote host is not heard from within a suitable timeout
67 For examples and usage, see the
68 .Qq "NTP Debugging Techniques"
70 (available as part of the HTML documentation
72 .Pa /usr/share/doc/ntp ) .
74 The following options are available:
75 .Bl -tag -width indent
77 The following argument is interpreted as an interactive format
78 command and is added to the list of commands to be executed on the
86 to operate in interactive mode.
88 will be written to the standard output and commands read from the
91 Output all host addresses in dotted-quad numeric format rather
92 than converting to the canonical host names.
94 Print a list of the peers known to the server as well as a
95 summary of their state.
96 This is equivalent to the
102 command line option other than
107 cause the specified query (queries) to be sent to the indicated
112 interactive format commands from the standard input.
113 .Ss "Internal Commands"
114 Interactive format commands consist of a keyword followed by zero
116 Only enough characters of the full keyword to
117 uniquely identify the command need be typed.
119 command is normally sent to the standard output, but optionally the
120 output of individual commands may be sent to a file by appending a
122 followed by a file name, to the command line.
124 number of interactive format commands are executed entirely within
127 utility itself and do not result in NTP mode 6
128 requests being sent to a server.
129 These are described following.
130 .Bl -tag -width indent
131 .It Ic \&? Op Ar command_keyword
132 .It Ic help Op Ar command_keyword
135 by itself will print a list of all the command
136 keywords known to this incarnation of
140 followed by a command keyword will print function and usage
141 information about the command.
142 This command is probably a better
143 source of information about
148 .Ar variable_name Ns Op = Ns Ar value ...
150 .It Ic rmvars Ar variable_name ...
152 The data carried by NTP mode 6 messages consists of a list of
154 .Ql variable_name=value ,
157 is ignored, and can be omitted,
158 in requests to the server to read variables.
161 utility maintains an internal list in which data to be included in control
162 messages can be assembled, and sent using the
166 commands described below.
169 command allows variables and their optional values to be added to
171 If more than one variable is to be added, the list should
172 be comma-separated and not contain white space.
175 command can be used to remove individual variables from the list,
178 command removes all variables from the
180 .It Ic authenticate Cm yes | Cm no
183 does not authenticate requests unless
184 they are write requests.
189 to send authentication with all requests it
191 Authenticated requests causes some servers to handle
192 requests slightly differently, and can occasionally melt the CPU in
193 fuzzballs if you turn authentication on before doing a
197 Causes output from query commands to be "cooked", so that
198 variables which are recognized by
201 values reformatted for human consumption.
204 thinks should have a decodable value but didn't are
205 marked with a trailing
212 Turns internal query program debugging on and off.
213 .It Ic delay Ar milliseconds
214 Specify a time interval to be added to timestamps included in
215 requests which require authentication.
216 This is used to enable
217 (unreliable) server reconfiguration over long delay network paths
218 or between machines whose clocks are unsynchronized.
220 server does not now require timestamps in authenticated requests,
221 so this command may be obsolete.
222 .It Ic host Ar hostname
223 Set the host to which future queries will be sent.
225 be either a host name or a numeric address.
226 .It Ic hostnames Cm yes | Cm no
229 is specified, host names are printed in
230 information displays.
233 is specified, numeric
234 addresses are printed instead.
238 modified using the command line
241 .It Ic keyid Ar keyid
242 This command allows the specification of a key number to be
243 used to authenticate configuration requests.
245 to a key number the server has been configured to use for this
253 Sets the NTP version number which
257 Defaults to 3, 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.
265 This command prompts you to type in a password (which will not
266 be echoed) which will be used to authenticate configuration
268 The password must correspond to the key configured for
269 use by the NTP server for this purpose if such requests are to be
272 Causes all output from query commands is printed as received
273 from the remote server.
274 The only formating/interpretation done on
275 the data is to transform nonascii data into a printable (but barely
276 understandable) form.
277 .It Ic timeout Ar milliseconds
278 Specify a timeout period for responses to server queries.
280 default is about 5000 milliseconds.
283 retries each query once after a timeout, the total waiting time for
284 a timeout will be twice the timeout value set.
286 .Ss Control Message Commands
287 Each peer known to an NTP server has a 16 bit integer association
288 identifier assigned to it.
289 NTP control messages which carry peer
290 variables must identify the peer the values correspond to by
291 including its association ID.
292 An association ID of 0 is special,
293 and indicates the variables are system variables, whose names are
294 drawn from a separate name space.
296 Control message commands result in one or more NTP mode 6
297 messages being sent to the server, and cause the data returned to
298 be printed in some format.
299 Most commands currently implemented send
300 a single message and expect a single response.
302 exceptions are the peers command, which will send a preprogrammed
303 series of messages to obtain the data it needs, and the mreadlist
304 and mreadvar commands, which will iterate over a range of
306 .Bl -tag -width indent
308 Obtains and prints a list of association identifiers and peer
309 statuses for in-spec peers of the server being queried.
312 The first of these is an index numbering the
313 associations from 1 for internal use, the second the actual
314 association identifier returned by the server and the third the
315 status word for the peer.
316 This is followed by a number of columns
317 containing data decoded from the status word.
318 See the peers command
325 command is cached internally
328 The index is then of use when dealing with stupid
329 servers which use association identifiers which are hard for humans
330 to type, in that for any subsequent commands which require an
331 association identifier as an argument, the form of index may be
332 used as an alternative.
333 .It Xo Ic clockvar Op Ar assocID
335 .Ar variable_name Ns Op = Ns Ar value ...
339 .It Xo Ic cv Op Ar assocID
341 .Ar variable_name Ns Op = Ns Ar value ...
345 Requests that a list of the server's clock variables be sent.
346 Servers which have a radio clock or other external synchronization
347 will respond positively to this.
348 If the association identifier is
349 omitted or zero the request is for the variables of the
351 and will generally get a positive response from all
352 servers with a clock.
353 If the server treats clocks as pseudo-peers,
354 and hence can possibly have more than one clock connected at once,
355 referencing the appropriate peer association ID will show the
356 variables of a particular clock.
357 Omitting the variable list will
358 cause the server to return a default variable display.
360 Obtains and prints a list of association identifiers and peer
361 statuses for all associations for which the server is maintaining
363 This command differs from the
366 only for servers which retain state for out-of-spec client
367 associations (i.e., fuzzballs).
368 Such associations are normally
369 omitted from the display when the
372 used, but are included in the output of
374 .It Ic lpassociations
375 Print data for all associations, including out-of-spec client
376 associations, from the internally cached list of associations.
380 only when dealing with
383 Like R peers, except a summary of all associations for which
384 the server is maintaining state is printed.
385 This can produce a much
386 longer list of peers from fuzzball servers.
387 .It Ic mreadlist Ar assocID Ar assocID
388 .It Ic mrl Ar assocID Ar assocID
391 command, except the query is done
392 for each of a range of (nonzero) association IDs.
394 determined from the association list cached by the most recent
397 .It Xo Ic mreadvar Ar assocID Ar assocID
399 .Ar variable_name Ns Op = Ns Ar value ...
402 .It Xo Ic mrv Ar assocID Ar assocID
404 .Ar variable_name Ns Op = Ns Ar value ...
409 command, except the query is done for
410 each of a range of (nonzero) association IDs.
412 determined from the association list cached by the most recent
418 command with the reference ID
419 replaced by the local interface address.
421 Displays association data concerning in-spec peers from the
422 internally cached list of associations.
423 This command performs
426 except that it displays
427 the internally stored data rather than making a new query.
429 Obtains a current list peers of the server, along with a
430 summary of each peer's state.
431 Summary information includes the
432 address of the remote peer, the reference ID (0.0.0.0 if this is
433 unknown), the stratum of the remote peer, the type of the peer
434 (local, unicast, multicast or broadcast), when the last packet was
435 received, the polling interval, in seconds, the reachability
436 register, in octal, and the current estimated delay, offset and
437 dispersion of the peer, all in milliseconds.
438 The character in the left margin indicates the fate of this
439 peer in the clock selection process.
440 Following is a list of these
441 characters, the pigeon used in the
444 explanation of the condition revealed.
445 .Bl -tag -width indent
448 The peer is discarded as unreachable, synchronized to this
449 server (synch loop) or outrageous synchronization distance.
452 The peer is discarded by the intersection algorithm as a
456 The peer is discarded as not among the first ten peers sorted
457 by synchronization distance and so is probably a poor candidate for
458 further consideration.
461 The peer is discarded by the clustering algorithm as an
465 The peer is a survivor and a candidate for the combining
469 The peer is a survivor, but not among the first six peers
470 sorted by synchronization distance.
471 If the association is ephemeral,
472 it may be demobilized to conserve resources.
475 The peer has been declared the system peer and lends its
476 variables to the system variables.
479 The peer has been declared the system peer and lends its
480 variables to the system variables.
481 However, the actual system
482 synchronization is derived from a pulse-per-second (PPS) signal,
483 either indirectly via the PPS reference clock driver or directly
484 via kernel interface.
490 variable is a valuable debugging aid.
492 displays the results of the original sanity checks defined in the
493 NTP specification RFC-1305 and additional ones added in NTP Version
495 There are eleven tests called
499 The tests are performed in a certain order
500 designed to gain maximum diagnostic information while protecting
501 against accidental or malicious errors.
505 is first initialized to zero.
506 If after each set of tests one or
507 more bits are set, the packet is discarded.
514 permissions and cryptographic message digest.
516 after that, the packet is discarded.
521 check the authentication state using Autokey
522 public-key cryptography, as described in the
523 .Sx Authentication Options
527 and the association has previously been marked reachable, the
528 packet is discarded; otherwise, the originate and receive
529 timestamps are saved, as required by the NTP protocol, and
530 processing continues.
537 timestamps from which the offset and delay are calculated.
539 bits are set, the packet is discarded; otherwise, the packet header
545 check the health of the server.
546 If any bits are set, the packet is
547 discarded; otherwise, the offset and delay relative to the server
548 are calculated and saved.
552 the association itself.
553 If any bits are set, the packet is
554 discarded; otherwise, the saved variables are passed to the clock
555 filter and mitigation algorithms.
559 bits for each test read in increasing order
560 from the least significant bit are defined as follows.
561 .Bl -tag -width indent
564 The packet is at best a casual retransmission
565 and at worst a malicious replay.
568 The packet is not a reply to a message previously
570 This can happen when the NTP daemon is restarted and before
571 somebody else notices.
574 One or more timestamp fields are invalid.
576 normally happens when the first packet from a peer is
584 Cryptographic authentication fails.
586 .Sx Authentication Options
590 The server is unsynchronized.
591 Wind up its clock first.
593 The server stratum is at the maximum than 15.
595 unsynchronized and its clock needs to be wound up.
597 Either the root delay or dispersion is greater than one second,
598 which is highly unlikely unless the peer is synchronized to
601 Either the peer delay or dispersion is greater than one second,
602 which is highly unlikely unless the peer is on Mars.
604 The autokey protocol has detected an authentication failure.
606 .Sx Authentication Options
610 The autokey protocol has not verified the server or peer is
611 authentic and has valid public key credentials.
613 .Sx Authentication Options
618 Additional system variables used by the NTP Version 4 Autokey
619 support include the following:
620 .Bl -tag -width indent
621 .It Ic certificate Ar filestamp
622 Shows the NTP seconds when the certificate file was
624 .It Ic hostname Ar host
625 Shows the name of the host as returned by the Unix
629 Shows the current flag bits, where the
632 are interpreted as follows:
633 .Bl -tag -width indent
637 RSA public/private key files present
639 PKI certificate file present
641 Diffie-Hellman parameters file present
643 NIST leapseconds table file present
645 .It Ic leapseconds Ar filestamp
646 Shows the NTP seconds when the NIST leapseconds table file was
648 .It Ic params Ar filestamp
649 Shows the NTP seconds when the Diffie-Hellman agreement
650 parameter file was created.
651 .It Ic publickey Ar filestamp
652 Shows the NTP seconds when the RSA public/private key files
654 .It Ic refresh Ar filestamp
655 Shows the NTP seconds when the public cryptographic values were
656 refreshed and signed.
658 Shows the TAI-UTC offset in seconds obtained from the NIST
662 Additional peer variables used by the NTP Version 4 Autokey
663 support include the following:
664 .Bl -tag -width indent
665 .It Ic certificate Ar filestamp
666 Shows the NTP seconds when the certificate file was
669 Shows the current flag bits, where the
672 interpreted as in the system variable of the same name.
674 are set in the first autokey message received from the server and
675 then reset as the associated data are obtained from the server and
677 .It Ic hcookie Ar hex
678 Shows the host cookie used in the key agreement algorithm.
679 .It Ic initkey Ar key
680 Shows the initial key used by the key list generator in the
682 .It Ic initsequence Ar index
683 Shows the initial index used by the key list generator in the
685 .It Ic pcookie Ar hex
686 Specifies the peer cookie used in the key agreement
688 .It Ic timestamp Ar time
689 Shows the NTP seconds when the last autokey key list was
690 generated and signed.
691 .It Ic pstatus Ar assocID
692 Sends a read status request to the server for the given
694 The names and values of the peer variables returned
696 Note that the status word from the header is
697 displayed preceding the variables, both in hexadecimal and in
699 .It Ic readlist Ar assocID
701 Requests that the values of the variables in the internal
702 variable list be returned by the server.
703 If the association ID is
704 omitted or is 0 the variables are assumed to be system variables.
705 Otherwise they are treated as peer variables.
707 variable list is empty a request is sent without data, which should
708 induce the remote server to return a default display.
709 .It Xo Ic readvar Ar assocID
710 .Ar variable_name Ns Op = Ns Ar value
713 .It Xo Ic rv Ar assocID
714 .Ar variable_name Ns Op = Ns Ar value
717 Requests that the values of the specified variables be returned
718 by the server by sending a read variables request.
720 association ID is omitted or is given as zero the variables are
721 system variables, otherwise they are peer variables and the values
722 returned will be those of the corresponding peer.
724 variable list will send a request with no data which should induce
725 the server to return a default display.
726 .It Xo Ic writevar Ar assocID
727 .Ar variable_name Ns Op = Ns Ar value
730 Like the readvar request, except the specified variables are
731 written instead of read.
732 .It Ic writelist Op Ar assocID
733 Like the readlist request, except the internal list variables
734 are written instead of read.
743 command is non-atomic and may occasionally result in
744 spurious error messages about invalid associations occurring and
745 terminating the command.
746 The timeout time is a fixed constant,
747 which means you wait a long time for timeouts since it assumes sort
749 The program should improve the timeout estimate as
750 it sends queries to a particular host, but doesn't.
nant's projects / dragonfly.git / blob