9 .Nd standard Network Time Protocol query program
17 is used to query NTP servers which implement the recommended NTP mode 6
18 control message format about current state and to request changes in
19 that state. The program may be run either in interactive mode or
20 controlled using command line arguments. Requests to read and write
21 arbitrary variables can be assembled, with raw and pretty\-printed
22 output options being available.
24 can also obtain and print a list of peers in a common format by sending
25 multiple queries to the server.
27 If one or more request options is included on the command line when
29 is executed, each of the requests will be sent to the NTP servers
30 running on each of the hosts given as command line arguments, or on
32 by default. If no request options are given,
34 will attempt to read commands from the standard input and execute these
35 on the NTP server running on the first host given on the command line,
39 when no other host is specified.
41 will prompt for commands if the standard input is a terminal device.
44 uses NTP mode 6 packets to communicate with the NTP server, and hence
45 can be used to query any compatable server on the network which permits
46 it. Note that since NTP is a UDP protocol this communication will be
47 somewhat unreliable, especially over large distances in terms of network
50 makes one attempt to retransmit requests, and will time requests out if
51 the remote host is not heard from within a suitable time out time.
53 Command line options are described following. Specifying a command line
58 will cause the specified query (queries) to be sent to the indicated
59 host(s) immediately. Otherwise,
61 will attempt to read interactive format commands from the standard
63 The following options are available:
64 .Bl -tag -width indent
66 The following argument is interpreted as an interactive format
68 and is added to the list of commands to be executed on the specified
75 to operate in interactive mode. Prompts will be written to the standard
76 output and commands read from the standard input.
78 Output all host addresses in dotted\-quad numeric format rather than
79 converting to the canonical host names.
81 Print a list of the peers known to the server as well as a summary of
82 their state. This is equivalent to the
88 Interactive format commands consist of a keyword followed by zero to
89 four arguments. Only enough characters of the full keyword to uniquely
90 identify the command need be typed. The output of a command is normally
91 sent to the standard output, but optionally the output of individual
92 commands may be sent to a file by appending a
94 followed by a file name, to the command line.
96 A number of interactive format commands are executed entirely within the
98 program itself and do not result in NTP mode 6 requests being sent to a
99 server. These are described following.
101 .Bl -tag -width indent
102 .It ? Op Ar command_keyword
105 by itself will print a list of all the command keywords
106 known to this incarnation of
110 followed by a command keyword will print function and
111 usage information about the command. This command is probably a better
112 source of information about
114 than this manual page.
115 .It timeout Ar milliseconds
116 Specify a time out period for responses to server queries. The default
117 is about 5000 milliseconds. Note that since
119 retries each query once after a time out the total waiting time for a
120 time out will be twice the time out value set.
121 .It delay Ar milliseconds
122 Specify a time interval to be added to timestamps included in requests
123 which require authentication. This is used to enable (unreliable) server
124 reconfiguration over long delay network paths or between machines whose
125 clocks are unsynchronized. Actually the server does not now require time
126 stamps in authenticated requests, so this command may be obsolete.
128 Set the host to which future queries will be sent.
130 may be either a host name or a numeric
136 Poll the current server in client mode. The first argument is the number
137 of times to poll (default is 1) while the second argument may be given
138 to obtain a more detailed output of the results. This command is
139 currently just wishful thinking.
141 This command allows the specification of a key number to be used to
142 authenticate configuration requests. This must correspond to a key
143 number the server has been configured to use for this purpose.
145 This command prompts you to type in a password (which will not be
146 echoed) which will be used to authenticate configuration requests. The
147 password must correspond to the key configured for use by the NTP server
148 for this purpose if such requests are to be successful.
149 .It hostnames Ar yes | Ar no
152 is specified, host names are printed in information
155 is given, numeric addresses are printed
156 instead. The default is
158 unless modified using the command line
162 Cause all output from query commands is printed as received from the
163 remote server. The only formating/intepretation done on the data is to
164 transform nonascii data into a printable (but barely understandable)
167 Cause output from query commands to be
170 which are recognized by the server will have their values reformatted
171 for human consumption. Variables which
173 thinks should have a decodeable value but didn't are marked with a
176 .It ntpversion Ar 1 | Ar 2 | Ar 3
177 Set the NTP version number which
179 claims in packets. Defaults to 3, Note that mode 6 control messages (and
180 modes, for that matter) didn't exist in NTP version 1. There appear to
181 be no servers left which demand version 1.
182 .It authenticate Ar yes | Ar no
185 does not authenticate requests unless they are write requests. The
190 to send authentication with all requests it makes. Authenticated
191 requests causes some servers to handle requests slightly differently,
192 and can occasionally melt the CPU in fuzzballs if you turn
193 authentication on before doing a peer display.
204 The data carried by NTP mode 6 messages consists of a list of items of
206 .Xo Aq variable_name Ns
211 is ignored, and can be omitted, in requests
212 to the server to read variables.
214 maintains an internal list in which data to be included in control
215 messages can be assembled, and sent using the
219 commands described below. The
221 command allows variables and their optional values to be added to the
222 list. If more than one variable is to be added, the list should be
223 comma\-separated and not contain white space. The
225 command can be used to remove individual variables from the list, while
228 command removes all variables from the list.
229 .It debug Ar more | Ar less | Ar off
230 Turn internal query program debugging on and off.
235 .Sh CONTROL MESSAGE COMMANDS
236 Each peer known to an NTP server has a 16 bit integer
237 .Em association identifier
238 assigned to it. NTP control messages which carry peer variables must
239 identify the peer the values correspond to by including its association
240 ID. An association ID of 0 is special, and indicates the variables are
241 system variables, whose names are drawn from a separate name space.
243 Control message commands result in one or more NTP mode 6 messages being
244 sent to the server, and cause the data returned to be printed in some
245 format. Most commands currently implemented send a single message and
246 expect a single response. The current exceptions are the
248 command, which will send a preprogrammed series of messages to obtain
249 the data it needs, and the
253 commands, which will iterate over a range of associations.
254 .Bl -tag -width indent
256 Obtain and print a list of association identifiers and peer statuses
257 for in\-spec peers of the server being queried. The list is printed in
258 columns. The first of these is an index numbering the associations from
259 1 for internal use, the second the actual association identifier
260 returned by the server and the third the status word for the peer. This
261 is followed by a number of columns containing data decoded from the
262 status word. Note that the data returned by the \*(L"associations\*(R"
263 command is cached internally in
265 The index is then of use when dealing with stupid servers which use
266 association identifiers which are hard for humans to type, in that for
267 any subsequent commands which require an association identifier as an
270 may be used as an alternative.
272 Obtain and print a list of association identifiers and peer statuses
273 for all associations for which the server is maintaining state. This
274 command differs from the
276 command only for servers
277 which retain state for out\-of\-spec client associations (i.e.
278 fuzzballs). Such associations are normally omitted from the display when
281 command is used, but are included in the
283 .Em lassociations Ns .
285 Print association data concerning in\-spec peers from the internally
286 cached list of associations. This command performs identically to the
288 except that it displays the internally stored
289 data rather than making a new query.
291 Print data for all associations, including out\-of\-spec client
292 associations, from the internally cached list of associations. This
295 only when dealing with fuzzballs.
296 .It pstatus Ar assocID
297 Send a read status request to the server for the given association. The
298 names and values of the peer variables returned will be printed. Note
299 that the status word from the header is displayed preceding the
300 variables, both in hexadecimal and in pidgin English.
303 .Pf [ Aq variable_name Ns
307 Request that the values of the specified variables be returned by the
308 server by sending a read variables request. If the association ID is
309 omitted or is given as zero the variables are system variables,
310 otherwise they are peer variables and the values returned will be those
311 of the corresponding peer. Omitting the variable list will send a
312 request with no data which should induce the server to return a default
316 .Pf [ Aq variable_name Ns
320 An easy\-to\-type short form for the
331 request, except the specified variables are written instead of read.
332 .It readlist Op Ar assocID
333 Request that the values of the variables in the internal variable list
334 be returned by the server. If the association ID is omitted or is 0 the
335 variables are assumed to be system variables. Otherwise they are treated
336 as peer variables. If the internal variable list is empty a request is
337 sent without data, which should induce the remote server to return a
340 An easy\-to\-type short form of the
343 .It writelist Op Ar assocID
346 request, except the internal list variables are written instead of read.
348 .Ar assocID assocID [
355 command except the query is done for each of a range of (nonzero)
356 association IDs. This range is determined from the association list
357 cached by the most recent
361 .Ar assocID assocID [
366 An easy\-to\-type short form of the
369 .It mreadlist Ar assocID assocID
372 command except the query is done for each of a range of (nonzero)
373 association IDs. This range is determined from the association list
374 cached by the most recent
377 .It mrl Ar assocID assocID
378 An easy\-to\-type short form of the
383 .Pf [ Aq variable_name Ns
387 Request that a list of the server's clock variables be sent. Servers
388 which have a radio clock or other external synchronization will respond
389 positively to this. If the association identifier is omitted or zero the
390 request is for the variables of the
393 generally get a positive response from all servers with a clock. If the
394 server treats clocks as pseudo\-peers, and hence can possibly have more
395 than one clock connected at once, referencing the appropriate peer
396 association ID will show the variables of a particular clock. Omitting
397 the variable list will cause the server to return a default variable
401 .Pf [ Aq variable_name Ns
405 An easy\-to\-type short form of the
409 Obtain a list of in\-spec peers of the server, along with a summary of
410 each peer's state. Summary information includes the address of the
411 remote peer, the reference ID (0.0.0.0 if the refID is unknown), the
412 stratum of the remote peer, the type of the peer (local, unicast,
413 multicast or broadcast), when the last packet was received, the polling
414 interval, in seconds, the reachability register, in octal, and the
415 current estimated delay, offset and dispersion of the peer, all in
418 The character in the left margin indicates the fate of this peer in the
419 clock selection process. The codes mean: <sp> discarded due to high
420 stratum and/or failed sanity checks;
422 designated falsticker
423 by the intersection algorithm;
425 culled from the end of the
428 discarded by the clustering algorithm;
430 included in the final selection set;
433 for synchronization but distance exceeds maximum;
436 for synchronization; and
438 selected for synchronization, pps
443 command depends on the ability to parse the values in the responses it
444 gets it may fail to work from time to time with servers which poorly
445 control the data formats.
447 The contents of the host field may be one of four forms. It may be a
448 host name, an IP address, a reference clock implementation name with its
450 .Qq REFCLK(<implementation number>, <parameter>) .
453 only IP\-addresses will be displayed.
457 except a summary of all associations for which the server is maintaining
458 state is printed. This can produce a much longer list of peers from
463 command with the reference ID
464 replaced by the local interface address.
469 at the University of Toronto.
473 command is non\-atomic and may occasionally result in spurious error
474 messages about invalid associations occurring and terminating the
477 The timeout time is a fixed constant, which means you wait a long time
478 for time outs since it assumes sort of a worst case. The program should
479 improve the time out estimate as it sends queries to a particular host,