2 .\" $FreeBSD: src/usr.sbin/ntp/doc/ntpq.8,v 1.3.2.9 2003/03/11 22:31:30 trhodes Exp $
9 .Nd standard NTP query program
18 utility is used to query NTP servers
19 which implement the recommended NTP mode 6 control message format
20 about current state and to request changes in that state.
22 program may be run either in interactive mode or controlled using
23 command line arguments.
24 Requests to read and write arbitrary
25 variables can be assembled, with raw and pretty-printed output
26 options being available.
29 utility can also obtain and print a
30 list of peers in a common format by sending multiple queries to the
33 If one or more request options is included on the command line
36 is executed, each of the requests will be sent
37 to the NTP servers running on each of the hosts given as command
38 line arguments, or on localhost by default.
42 will attempt to read commands from the
43 standard input and execute these on the NTP server running on the
44 first host given on the command line, again defaulting to localhost
45 when no other host is specified.
48 utility will prompt for
49 commands if the standard input is a terminal device.
53 utility uses NTP mode 6 packets to communicate with the
54 NTP server, and hence can be used to query any compatible server on
55 the network which permits it.
56 Note that since NTP is a UDP protocol
57 this communication will be somewhat unreliable, especially over
58 large distances in terms of network topology.
62 one attempt to retransmit requests, and will time requests out if
63 the remote host is not heard from within a suitable timeout
66 For examples and usage, see the
67 .Qq "NTP Debugging Techniques"
69 (available as part of the HTML documentation
71 .Pa /usr/share/doc/ntp ) .
73 The following options are available:
74 .Bl -tag -width indent
76 The following argument is interpreted as an interactive format
77 command and is added to the list of commands to be executed on the
85 to operate in interactive mode.
87 will be written to the standard output and commands read from the
90 Output all host addresses in dotted-quad numeric format rather
91 than converting to the canonical host names.
93 Print a list of the peers known to the server as well as a
94 summary of their state.
95 This is equivalent to the
101 command line option other than
106 cause the specified query (queries) to be sent to the indicated
111 interactive format commands from the standard input.
112 .Ss "Internal Commands"
113 Interactive format commands consist of a keyword followed by zero
115 Only enough characters of the full keyword to
116 uniquely identify the command need be typed.
118 command is normally sent to the standard output, but optionally the
119 output of individual commands may be sent to a file by appending a
121 followed by a file name, to the command line.
123 number of interactive format commands are executed entirely within
126 utility itself and do not result in NTP mode 6
127 requests being sent to a server.
128 These are described following.
129 .Bl -tag -width indent
130 .It Ic \&? Op Ar command_keyword
131 .It Ic help Op Ar command_keyword
134 by itself will print a list of all the command
135 keywords known to this incarnation of
139 followed by a command keyword will print function and usage
140 information about the command.
141 This command is probably a better
142 source of information about
147 .Ar variable_name Ns Op = Ns Ar value ...
149 .It Ic rmvars Ar variable_name ...
151 The data carried by NTP mode 6 messages consists of a list of
153 .Ql variable_name=value ,
156 is ignored, and can be omitted,
157 in requests to the server to read variables.
160 utility maintains an internal list in which data to be included in control
161 messages can be assembled, and sent using the
165 commands described below.
168 command allows variables and their optional values to be added to
170 If more than one variable is to be added, the list should
171 be comma-separated and not contain white space.
174 command can be used to remove individual variables from the list,
177 command removes all variables from the
179 .It Ic authenticate Cm yes | Cm no
182 does not authenticate requests unless
183 they are write requests.
188 to send authentication with all requests it
190 Authenticated requests causes some servers to handle
191 requests slightly differently, and can occasionally melt the CPU in
192 fuzzballs if you turn authentication on before doing a
196 Causes output from query commands to be "cooked", so that
197 variables which are recognized by
200 values reformatted for human consumption.
203 thinks should have a decodable value but didn't are
204 marked with a trailing
211 Turns internal query program debugging on and off.
212 .It Ic delay Ar milliseconds
213 Specify a time interval to be added to timestamps included in
214 requests which require authentication.
215 This is used to enable
216 (unreliable) server reconfiguration over long delay network paths
217 or between machines whose clocks are unsynchronized.
219 server does not now require timestamps in authenticated requests,
220 so this command may be obsolete.
221 .It Ic host Ar hostname
222 Set the host to which future queries will be sent.
224 be either a host name or a numeric address.
225 .It Ic hostnames Cm yes | Cm no
228 is specified, host names are printed in
229 information displays.
232 is specified, numeric
233 addresses are printed instead.
237 modified using the command line
240 .It Ic keyid Ar keyid
241 This command allows the specification of a key number to be
242 used to authenticate configuration requests.
244 to a key number the server has been configured to use for this
252 Sets the NTP version number which
256 Defaults to 3, Note that mode 6 control messages (and
257 modes, for that matter) didn't exist in NTP version 1.
259 to be no servers left which demand version 1.
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
271 Causes all output from query commands is printed as received
272 from the remote server.
273 The only formating/interpretation done on
274 the data is to transform nonascii data into a printable (but barely
275 understandable) form.
276 .It Ic timeout Ar milliseconds
277 Specify a timeout period for responses to server queries.
279 default is about 5000 milliseconds.
282 retries each query once after a timeout, the total waiting time for
283 a timeout will be twice the timeout value set.
285 .Ss Control Message Commands
286 Each peer known to an NTP server has a 16 bit integer association
287 identifier assigned to it.
288 NTP control messages which carry peer
289 variables must identify the peer the values correspond to by
290 including its association ID.
291 An association ID of 0 is special,
292 and indicates the variables are system variables, whose names are
293 drawn from a separate name space.
295 Control message commands result in one or more NTP mode 6
296 messages being sent to the server, and cause the data returned to
297 be printed in some format.
298 Most commands currently implemented send
299 a single message and expect a single response.
301 exceptions are the peers command, which will send a preprogrammed
302 series of messages to obtain the data it needs, and the mreadlist
303 and mreadvar commands, which will iterate over a range of
305 .Bl -tag -width indent
307 Obtains and prints a list of association identifiers and peer
308 statuses for in-spec peers of the server being queried.
311 The first of these is an index numbering the
312 associations from 1 for internal use, the second the actual
313 association identifier returned by the server and the third the
314 status word for the peer.
315 This is followed by a number of columns
316 containing data decoded from the status word.
317 See the peers command
324 command is cached internally
327 The index is then of use when dealing with stupid
328 servers which use association identifiers which are hard for humans
329 to type, in that for any subsequent commands which require an
330 association identifier as an argument, the form of index may be
331 used as an alternative.
332 .It Xo Ic clockvar Op Ar assocID
334 .Ar variable_name Ns Op = Ns Ar value ...
338 .It Xo Ic cv Op Ar assocID
340 .Ar variable_name Ns Op = Ns Ar value ...
344 Requests that a list of the server's clock variables be sent.
345 Servers which have a radio clock or other external synchronization
346 will respond positively to this.
347 If the association identifier is
348 omitted or zero the request is for the variables of the
350 and will generally get a positive response from all
351 servers with a clock.
352 If the server treats clocks as pseudo-peers,
353 and hence can possibly have more than one clock connected at once,
354 referencing the appropriate peer association ID will show the
355 variables of a particular clock.
356 Omitting the variable list will
357 cause the server to return a default variable display.
359 Obtains and prints a list of association identifiers and peer
360 statuses for all associations for which the server is maintaining
362 This command differs from the
365 only for servers which retain state for out-of-spec client
366 associations (i.e., fuzzballs).
367 Such associations are normally
368 omitted from the display when the
371 used, but are included in the output of
373 .It Ic lpassociations
374 Print data for all associations, including out-of-spec client
375 associations, from the internally cached list of associations.
379 only when dealing with
382 Like R peers, except a summary of all associations for which
383 the server is maintaining state is printed.
384 This can produce a much
385 longer list of peers from fuzzball servers.
386 .It Ic mreadlist Ar assocID Ar assocID
387 .It Ic mrl Ar assocID Ar assocID
390 command, except the query is done
391 for each of a range of (nonzero) association IDs.
393 determined from the association list cached by the most recent
396 .It Xo Ic mreadvar Ar assocID Ar assocID
398 .Ar variable_name Ns Op = Ns Ar value ...
401 .It Xo Ic mrv Ar assocID Ar assocID
403 .Ar variable_name Ns Op = Ns Ar value ...
408 command, except the query is done for
409 each of a range of (nonzero) association IDs.
411 determined from the association list cached by the most recent
417 command with the reference ID
418 replaced by the local interface address.
420 Displays association data concerning in-spec peers from the
421 internally cached list of associations.
422 This command performs
425 except that it displays
426 the internally stored data rather than making a new query.
428 Obtains a current list peers of the server, along with a
429 summary of each peer's state.
430 Summary information includes the
431 address of the remote peer, the reference ID (0.0.0.0 if this is
432 unknown), the stratum of the remote peer, the type of the peer
433 (local, unicast, multicast or broadcast), when the last packet was
434 received, the polling interval, in seconds, the reachability
435 register, in octal, and the current estimated delay, offset and
436 dispersion of the peer, all in milliseconds.
437 The character in the left margin indicates the fate of this
438 peer in the clock selection process.
439 Following is a list of these
440 characters, the pigeon used in the
443 explanation of the condition revealed.
444 .Bl -tag -width indent
447 The peer is discarded as unreachable, synchronized to this
448 server (synch loop) or outrageous synchronization distance.
451 The peer is discarded by the intersection algorithm as a
455 The peer is discarded as not among the first ten peers sorted
456 by synchronization distance and so is probably a poor candidate for
457 further consideration.
460 The peer is discarded by the clustering algorithm as an
464 The peer is a survivor and a candidate for the combining
468 The peer is a survivor, but not among the first six peers
469 sorted by synchronization distance.
470 If the association is ephemeral,
471 it may be demobilized to conserve resources.
474 The peer has been declared the system peer and lends its
475 variables to the system variables.
478 The peer has been declared the system peer and lends its
479 variables to the system variables.
480 However, the actual system
481 synchronization is derived from a pulse-per-second (PPS) signal,
482 either indirectly via the PPS reference clock driver or directly
483 via kernel interface.
489 variable is a valuable debugging aid.
491 displays the results of the original sanity checks defined in the
492 NTP specification RFC-1305 and additional ones added in NTP Version
494 There are eleven tests called
498 The tests are performed in a certain order
499 designed to gain maximum diagnostic information while protecting
500 against accidental or malicious errors.
504 is first initialized to zero.
505 If after each set of tests one or
506 more bits are set, the packet is discarded.
513 permissions and cryptographic message digest.
515 after that, the packet is discarded.
520 check the authentication state using Autokey
521 public-key cryptography, as described in the
522 .Sx Authentication Options
526 and the association has previously been marked reachable, the
527 packet is discarded; otherwise, the originate and receive
528 timestamps are saved, as required by the NTP protocol, and
529 processing continues.
536 timestamps from which the offset and delay are calculated.
538 bits are set, the packet is discarded; otherwise, the packet header
544 check the health of the server.
545 If any bits are set, the packet is
546 discarded; otherwise, the offset and delay relative to the server
547 are calculated and saved.
551 the association itself.
552 If any bits are set, the packet is
553 discarded; otherwise, the saved variables are passed to the clock
554 filter and mitigation algorithms.
558 bits for each test read in increasing order
559 from the least significant bit are defined as follows.
560 .Bl -tag -width indent
563 The packet is at best a casual retransmission
564 and at worst a malicious replay.
567 The packet is not a reply to a message previously
569 This can happen when the NTP daemon is restarted and before
570 somebody else notices.
573 One or more timestamp fields are invalid.
575 normally happens when the first packet from a peer is
583 Cryptographic authentication fails.
585 .Sx Authentication Options
589 The server is unsynchronized.
590 Wind up its clock first.
592 The server stratum is at the maximum than 15.
594 unsynchronized and its clock needs to be wound up.
596 Either the root delay or dispersion is greater than one second,
597 which is highly unlikely unless the peer is synchronized to
600 Either the peer delay or dispersion is greater than one second,
601 which is highly unlikely unless the peer is on Mars.
603 The autokey protocol has detected an authentication failure.
605 .Sx Authentication Options
609 The autokey protocol has not verified the server or peer is
610 authentic and has valid public key credentials.
612 .Sx Authentication Options
617 Additional system variables used by the NTP Version 4 Autokey
618 support include the following:
619 .Bl -tag -width indent
620 .It Ic certificate Ar filestamp
621 Shows the NTP seconds when the certificate file was
623 .It Ic hostname Ar host
624 Shows the name of the host as returned by the Unix
628 Shows the current flag bits, where the
631 are interpreted as follows:
632 .Bl -tag -width indent
636 RSA public/private key files present
638 PKI certificate file present
640 Diffie-Hellman parameters file present
642 NIST leapseconds table file present
644 .It Ic leapseconds Ar filestamp
645 Shows the NTP seconds when the NIST leapseconds table file was
647 .It Ic params Ar filestamp
648 Shows the NTP seconds when the Diffie-Hellman agreement
649 parameter file was created.
650 .It Ic publickey Ar filestamp
651 Shows the NTP seconds when the RSA public/private key files
653 .It Ic refresh Ar filestamp
654 Shows the NTP seconds when the public cryptographic values were
655 refreshed and signed.
657 Shows the TAI-UTC offset in seconds obtained from the NIST
661 Additional peer variables used by the NTP Version 4 Autokey
662 support include the following:
663 .Bl -tag -width indent
664 .It Ic certificate Ar filestamp
665 Shows the NTP seconds when the certificate file was
668 Shows the current flag bits, where the
671 interpreted as in the system variable of the same name.
673 are set in the first autokey message received from the server and
674 then reset as the associated data are obtained from the server and
676 .It Ic hcookie Ar hex
677 Shows the host cookie used in the key agreement algorithm.
678 .It Ic initkey Ar key
679 Shows the initial key used by the key list generator in the
681 .It Ic initsequence Ar index
682 Shows the initial index used by the key list generator in the
684 .It Ic pcookie Ar hex
685 Specifies the peer cookie used in the key agreement
687 .It Ic timestamp Ar time
688 Shows the NTP seconds when the last autokey key list was
689 generated and signed.
690 .It Ic pstatus Ar assocID
691 Sends a read status request to the server for the given
693 The names and values of the peer variables returned
695 Note that the status word from the header is
696 displayed preceding the variables, both in hexadecimal and in
698 .It Ic readlist Ar assocID
700 Requests that the values of the variables in the internal
701 variable list be returned by the server.
702 If the association ID is
703 omitted or is 0 the variables are assumed to be system variables.
704 Otherwise they are treated as peer variables.
706 variable list is empty a request is sent without data, which should
707 induce the remote server to return a default display.
708 .It Xo Ic readvar Ar assocID
709 .Ar variable_name Ns Op = Ns Ar value
712 .It Xo Ic rv Ar assocID
713 .Ar variable_name Ns Op = Ns Ar value
716 Requests that the values of the specified variables be returned
717 by the server by sending a read variables request.
719 association ID is omitted or is given as zero the variables are
720 system variables, otherwise they are peer variables and the values
721 returned will be those of the corresponding peer.
723 variable list will send a request with no data which should induce
724 the server to return a default display.
725 .It Xo Ic writevar Ar assocID
726 .Ar variable_name Ns Op = Ns Ar value
729 Like the readvar request, except the specified variables are
730 written instead of read.
731 .It Ic writelist Op Ar assocID
732 Like the readlist request, except the internal list variables
733 are written instead of read.
742 command is non-atomic and may occasionally result in
743 spurious error messages about invalid associations occurring and
744 terminating the command.
745 The timeout time is a fixed constant,
746 which means you wait a long time for timeouts since it assumes sort
748 The program should improve the timeout estimate as
749 it sends queries to a particular host, but doesn't.
uqs's projects / games.git / blob