9 .Nd standard NTP query program
19 utility is used to monitor NTP daemon
21 operations and determine performance.
22 It uses the standard NTP mode 6 control message formats
23 defined in Appendix B of the NTPv3 specification RFC1305.
24 The same formats are used in NTPv4, although some of the variables
25 have changed and new ones added.
26 The description on this page is for the NTPv4 variables.
28 The program can be run either in interactive mode or controlled
29 using command line arguments.
30 Requests to read and write arbitrary variables can be assembled,
31 with raw and pretty-printed output options being available.
34 can also obtain and print a list of peers in a common format
35 by sendingmultiple queries to the server.
37 If one or more request options is included on the command line
40 is executed, each of the requests will be sent
41 to the NTP servers running on each of the hosts given as command
42 line arguments, or on localhost by default.
46 will attempt to read commands from the
47 standard input and execute these on the NTP server running on the
48 first host given on the command line, again defaulting to localhost
49 when no other host is specified.
52 utility will prompt for
53 commands if the standard input is a terminal device.
57 utility uses NTP mode 6 packets to communicate with the
58 NTP server, and hence can be used to query any compatible server on
59 the network which permits it.
60 Note that since NTP is a UDP protocol
61 this communication will be somewhat unreliable, especially over
62 large distances in terms of network topology.
66 one attempt to retransmit requests, and will time requests out if
67 the remote host is not heard from within a suitable timeout
70 For examples and usage, see the
71 .Qq NTP Debugging Techniques
73 (available as part of the HTML documentation
75 .Pa /usr/share/doc/ntp ) .
77 The following options are available:
78 .Bl -tag -width indent
80 Force DNS resolution of following host names on the command line to the
83 Force DNS resolution of following host names on the command line to the
86 The following argument is interpreted as an interactive format
87 command and is added to the list of commands to be executed on the
93 Turn on debugging mode.
97 to operate in interactive mode.
99 will be written to the standard output and commands read from the
102 Output all host addresses in dotted-quad numeric format rather
103 than converting to the canonical host names.
105 Print a list of the peers known to the server as well as a
106 summary of their state.
107 This is equivalent to the
112 Note that in contexts where a host name is expected, a
114 qualifier preceding the host name forces DNS resolution to the
115 IPv4 namespace, while a
117 qualifier forces DNS resolution to the IPv6 namespace.
119 command line option other than
124 cause the specified query (queries) to be sent to the indicated
129 interactive format commands from the standard input.
130 .Ss "Internal Commands"
131 Interactive format commands consist of a keyword followed by zero
133 Only enough characters of the full keyword to
134 uniquely identify the command need be typed.
136 command is normally sent to the standard output, but optionally the
137 output of individual commands may be sent to a file by appending a
139 followed by a file name, to the command line.
141 number of interactive format commands are executed entirely within
144 utility itself and do not result in NTP mode 6
145 requests being sent to a server.
146 These are described following.
147 .Bl -tag -width indent
148 .It Ic \&? Op Ar command_keyword
149 .It Ic help Op Ar command_keyword
152 by itself will print a list of all the command
153 keywords known to this incarnation of
157 followed by a command keyword will print function and usage
158 information about the command.
159 This command is probably a better
160 source of information about
165 .Ar variable_name Ns Op = Ns Ar value ...
167 .It Ic rmvars Ar variable_name ...
169 The data carried by NTP mode 6 messages consists of a list of
171 .Ql variable_name=value ,
174 is ignored, and can be omitted,
175 in requests to the server to read variables.
178 utility maintains an internal list in which data to be included in control
179 messages can be assembled, and sent using the
183 commands described below.
186 command allows variables and their optional values to be added to
188 If more than one variable is to be added, the list should
189 be comma-separated and not contain white space.
192 command can be used to remove individual variables from the list,
195 command removes all variables from the
198 Causes output from query commands to be "cooked", so that
199 variables which are recognized by
202 values reformatted for human consumption.
205 thinks should have a decodable value but did not are
206 marked with a trailing
213 Turns internal query program debugging on and off.
214 .It Ic delay Ar milliseconds
215 Specify a time interval to be added to timestamps included in
216 requests which require authentication.
217 This is used to enable
218 (unreliable) server reconfiguration over long delay network paths
219 or between machines whose clocks are unsynchronized.
221 server does not now require timestamps in authenticated requests,
222 so this command may be obsolete.
223 .It Ic host Ar hostname
224 Set the host to which future queries will be sent.
226 be either a host name or a numeric address.
227 .It Ic hostnames Cm yes | Cm no
230 is specified, host names are printed in
231 information displays.
234 is specified, numeric
235 addresses are printed instead.
239 modified using the command line
242 .It Ic keyid Ar keyid
243 This command specifies the key number to be used to authenticate
244 configuration requests.
245 This must correspond to a key number the server has
246 been configured to use for this purpose.
253 Sets the NTP version number which
257 Defaults to 3, Note that mode 6 control messages (and
258 modes, for that matter) did not exist in NTP version 1.
260 to be no servers left which demand version 1.
262 This command prompts for a password (which will not be echoed) which will
263 be used to authenticate configuration requests.
265 correspond to the key configured for NTP server for this purpose.
270 Causes all output from query commands is printed as received
271 from the remote server.
272 The only formatting/interpretation done on
273 the data is to transform nonascii data into a printable (but barely
274 understandable) form.
275 .It Ic timeout Ar milliseconds
276 Specify a timeout period for responses to server queries.
278 default is about 5000 milliseconds.
281 retries each query once after a timeout, the total waiting time for
282 a timeout will be twice the timeout value set.
284 .Ss Control Message Commands
285 Each association known to an NTP server has a 16 bit integer association
287 NTP control messages which carry peer variables must identify the
288 peer the values correspond to by including its association ID.
290 ID of 0 is special, and indicates the variables are system variables, whose
291 names are drawn from a separate name space.
293 Control message commands result in one or more NTP mode 6
294 messages being sent to the server, and cause the data returned to
295 be printed in some format.
296 Most commands currently implemented send
297 a single message and expect a single response.
299 exceptions are the peers command, which will send a preprogrammed
300 series of messages to obtain the data it needs, and the mreadlist
301 and mreadvar commands, which will iterate over a range of
303 .Bl -tag -width indent
305 Obtains and prints a list of association identifiers and peer
306 statuses for in-spec peers of the server being queried.
309 The first of these is an index numbering the
310 associations from 1 for internal use, the second the actual
311 association identifier returned by the server and the third the
312 status word for the peer.
313 This is followed by a number of columns
314 containing data decoded from the status word.
315 See the peers command
322 command is cached internally
325 The index is then of use when dealing with stupid
326 servers which use association identifiers which are hard for humans
327 to type, in that for any subsequent commands which require an
328 association identifier as an argument, the form and index may be
329 used as an alternative.
330 .It Xo Ic clockvar Op Ar assocID
332 .Ar variable_name Ns Op = Ns Ar value ...
336 .It Xo Ic cv Op Ar assocID
338 .Ar variable_name Ns Op = Ns Ar value ...
342 Requests that a list of the server's clock variables be sent.
343 Servers which have a radio clock or other external synchronization
344 will respond positively to this.
345 If the association identifier is
346 omitted or zero the request is for the variables of the
348 and will generally get a positive response from all
349 servers with a clock.
350 If the server treats clocks as pseudo-peers,
351 and hence can possibly have more than one clock connected at once,
352 referencing the appropriate peer association ID will show the
353 variables of a particular clock.
354 Omitting the variable list will
355 cause the server to return a default variable display.
357 Obtains and prints a list of association identifiers and peer
358 statuses for all associations for which the server is maintaining
360 This command differs from the
363 only for servers which retain state for out-of-spec client
364 associations (i.e., fuzzballs).
365 Such associations are normally
366 omitted from the display when the
369 used, but are included in the output of
371 .It Ic lpassociations
372 Print data for all associations, including out-of-spec client
373 associations, from the internally cached list of associations.
377 only when dealing with
380 Like R peers, except a summary of all associations for which
381 the server is maintaining state is printed.
382 This can produce a much
383 longer list of peers from fuzzball servers.
384 .It Ic mreadlist Ar assocID Ar assocID
385 .It Ic mrl Ar assocID Ar assocID
388 command, except the query is done
389 for each of a range of (nonzero) association IDs.
391 determined from the association list cached by the most recent
394 .It Xo Ic mreadvar Ar assocID Ar assocID
396 .Ar variable_name Ns Op = Ns Ar value ...
399 .It Xo Ic mrv Ar assocID Ar assocID
401 .Ar variable_name Ns Op = Ns Ar value ...
406 command, except the query is done for
407 each of a range of (nonzero) association IDs.
409 determined from the association list cached by the most recent
415 command with the reference ID
416 replaced by the local interface address.
418 Displays association data concerning in-spec peers from the
419 internally cached list of associations.
420 This command performs
423 except that it displays
424 the internally stored data rather than making a new query.
426 Obtains a current list peers of the server, along with a
427 summary of each peer's state.
428 Summary information includes the
429 address of the remote peer, the reference ID (0.0.0.0 if this is
430 unknown), the stratum of the remote peer, the type of the peer
431 (local, unicast, multicast or broadcast), when the last packet was
432 received, the polling interval, in seconds, the reachability
433 register, in octal, and the current estimated delay,
434 offset and dispersion of the peer, all in milliseconds.
435 The character at the left margin of each line shows the
436 synchronization status of the association and is a valuable
438 The encoding and meaning of this character,
439 called the tally code, is given later in this page.
440 .It Ic pstatus Ar assocID
441 Sends a read status request to the server for the given
443 The names and values of the peer variables returned
445 Note that the status word from the header is
446 displayed preceding the variables, both in hexadecimal and in
448 .It Ic readlist Ar assocID
450 Requests that the values of the variables in the internal
451 variable list be returned by the server.
452 If the association ID is
453 omitted or is 0 the variables are assumed to be system variables.
454 Otherwise they are treated as peer variables.
456 variable list is empty a request is sent without data, which should
457 induce the remote server to return a default display.
458 .It Xo Ic readvar Ar assocID
459 .Ar variable_name Ns Op = Ns Ar value
462 .It Xo Ic rv Ar assocID
463 .Ar variable_name Ns Op = Ns Ar value
466 Requests that the values of the specified variables be returned
467 by the server by sending a read variables request.
469 association ID is omitted or is given as zero the variables are
470 system variables, otherwise they are peer variables and the values
471 returned will be those of the corresponding peer.
473 variable list will send a request with no data which should induce
474 the server to return a default display.
476 encoding and meaning of the variables derived from NTPv3 is given in
477 RFC-1305; the encoding and meaning of the additional NTPv4 variables are
478 given later in this page.
479 .It Xo Ic writevar Ar assocID
480 .Ar variable_name Ns Op = Ns Ar value
483 Like the readvar request, except the specified variables are
484 written instead of read.
485 .It Ic writelist Op Ar assocID
486 Like the readlist request, except the internal list variables
487 are written instead of read.
490 The character in the left margin in the
493 called the tally code, shows the fate of each association
494 in the clock selection process.
495 Following is a list of these characters, the pigeon used
498 command, and a short explanation of the condition revealed.
499 .Bl -tag -width indent
502 The peer is discarded as unreachable, synchronized to this server (synch
503 loop) or outrageous synchronization distance.
506 The peer is discarded by the intersection algorithm as a falseticker.
509 The peer is discarded as not among the first ten peers sorted by
510 synchronization distance and so is probably a poor candidate for further
514 The peer is discarded by the clustering algorithm as an outlyer.
517 The peer is a survivor and a candidate for the combining algorithm.
520 The peer is a survivor, but not among the first six peers sorted by
521 synchronization distance.
522 If the association is ephemeral, it may be
523 demobilized to conserve resources.
526 The peer has been declared the system peer and lends its variables to the
530 The peer has been declared the system peer and lends its variables to
531 the system variables.
532 However, the actual system synchronization is derived
533 from a pulse-per-second (PPS) signal, either indirectly via the PPS
534 reference clock driver or directly via kernel interface.
550 variables are described in RFC-1305
552 Additional NTPv4 system variables include the following.
553 .Bl -tag -width indent
555 Everything you might need to know about the software version and generation
558 The processor and kernel identification string.
560 The operating system version and release identifier.
562 The state of the clock discipline state machine.
563 The values are described
564 in the architecture briefing on the NTP Project page linked from
567 The internal integer used to identify the association currently designated
570 The estimated time error of the system clock measured as an exponential
571 average of RMS time differences.
573 The estimated frequency stability of the system clock measured as an
574 exponential average of RMS frequency differences.
577 When the NTPv4 daemon is compiled with the OpenSSL software library, additional
578 system variables are displayed, including some or all of the following,
579 depending on the particular dance:
580 .Bl -tag -width indent
582 The current flags word bits and message digest algorithm identifier (NID)
584 The high order 16 bits of the four-byte word contain the NID
585 from the OpenSSL ligrary, while the low-order bits are interpreted as
587 .Bl -tag -width indent
591 NIST leapseconds file loaded
600 The name of the host as returned by the Unix
605 The NTP filestamp of the host key file.
607 A list of certificates held by the host.
608 Each entry includes the subject,
609 issuer, flags and NTP filestamp in order.
610 The bits are interpreted as
612 .Bl -tag -width indent
614 certificate has been signed by the server
616 certificate is trusted
618 certificate is private
620 certificate contains errors and should not be trusted
623 The NTP filestamp of the NIST leapseconds file.
625 The NTP timestamp when the host public cryptographic values were refreshed
628 The host digest/signature scheme name from the OpenSSL library.
630 The TAI-UTC offset in seconds obtained from the NIST leapseconds table.
653 variables are described in the RFC-1305 specification, as
659 Additional NTPv4 system variables include
661 .Bl -tag -width indent
663 The flash code for the most recent packet received.
665 meaning of these codes is given later in this page.
667 The estimated time error of the peer clock measured as an exponential
668 average of RMS time differences.
670 The value of the counter which records the number of poll intervals since
671 the last valid packet was received.
674 When the NTPv4 daemon is compiled with the OpenSSL software library, additional
675 peer variables are displayed, including the following:
676 .Bl -tag -width indent
678 The current flag bits.
679 This word is the server host status word with
680 additional bits used by the Autokey state machine.
681 See the source code for
684 The server host name.
686 The initial key used by the key list generator in the Autokey protocol.
687 .It initsequence Ar index
688 The initial index used by the key list generator in the Autokey protocol.
690 The server message digest/signature scheme name from the OpenSSL software
692 .It timestamp Ar time
693 The NTP timestamp when the last Autokey key list was generated and signed.
698 code is a valuable debugging aid displayed in the peer variables
700 It shows the results of the original sanity checks defined in the NTP
701 specification RFC-1305 and additional ones added in NTPv4.
707 The tests are performed in a certain order
708 designed to gain maximum diagnostic information while protecting against
709 accidental or malicious errors.
712 variable is initialized to zero as
713 each packet is received.
714 If after each set of tests one or more bits are set,
715 the packet is discarded.
721 check the packet timestamps from which the offset and
722 delay are calculated.
723 If any bits are set, the packet is discarded; otherwise,
724 the packet header variables are saved.
729 access control and cryptographic authentication.
730 If any bits are set, the
731 packet is discarded immediately with nothing changed.
737 check the health of the server.
739 the packet is discarded; otherwise, the offset and delay relative to the server
740 are calculated and saved.
741 TEST9 checks the health of the association itself.
743 any bits are set, the packet is discarded; otherwise, the saved variables are
744 passed to the clock filter and mitigation algorithms.
750 check the authentication state using Autokey
751 public-key cryptography, as described in the
752 .Sx Authentication Options
756 any bits are set and the association has previously been marked reachable, the
757 packet is discarded; otherwise, the originate and receive timestamps are saved,
758 as required by the NTP protocol, and processing continues.
762 bits for each test are defined as follows.
763 .Bl -tag -width indent
767 The packet is at best a casual retransmission and at
768 worst a malicious replay.
772 The packet is not a reply to a message previously sent.
774 can happen when the NTP daemon is restarted and before somebody else
779 One or more timestamp fields are invalid.
781 happens when the first packet from a peer is received.
786 .Sx Access Control Support
791 Cryptographic authentication fails.
793 .Sx Authentication Options
798 The server is unsynchronized.
799 Wind up its clock first.
802 The server stratum is at the maximum than 15.
803 It is probably unsynchronized
804 and its clock needs to be wound up.
807 Either the root delay or dispersion is greater than one second, which is
808 highly unlikely unless the peer is unsynchronized to Mars.
811 Either the peer delay or dispersion is greater than one second, which is
812 higly unlikely unless the peer is on Mars.
815 The autokey protocol has detected an authentication failure.
817 .Sx Authentication Options
822 The autokey protocol has not verified the server or peer is proventic and
823 has valid public key credentials.
825 .Sx Authentication Options
830 A protocol or configuration error has occurred in the public key algorithms
831 or a possible intrusion event has been detected.
833 .Sx Authentication Options
844 command is non-atomic and may occasionally result in
845 spurious error messages about invalid associations occurring and
846 terminating the command.
847 The timeout time is a fixed constant,
848 which means you wait a long time for timeouts since it assumes sort
850 The program should improve the timeout estimate as
851 it sends queries to a particular host, but does not.
projects / FreeBSD / releng / 10.0.git / blob