| blob | c117c6435a9a8ca4f5c0de74cd58007a8f140e2a |
1 .TH NTPQ 1 2009-12-08 "( 4.2.4p8)" "Programmer's Manual"
2 .\" EDIT THIS FILE WITH CAUTION (ntpq.1)
3 .\"
4 .\" It has been AutoGen-ed Tuesday December 8, 2009 at 08:14:27 AM EST
5 .\" From the definitions ntpq-opts.def
6 .\" and the template file agman1.tpl
7 .\"
8 .SH NAME
9 ntpq \- standard NTP query program
10 .SH SYNOPSIS
11 .B ntpq
12 .\" Mixture of short (flag) options and long options
13 .RB [ \-\fIflag\fP " [\fIvalue\fP]]... [" \--\fIopt-name\fP " [[=| ]\fIvalue\fP]]..."
14 .br
15 .in +8
16 [ host ...]
17 .SH "DESCRIPTION"
18 This manual page documents, briefly, the \fBntpq\fP command.
19 The
20 ntpq
21 utility program is used to query NTP servers which
22 implement the standard NTP mode 6 control message formats defined
23 in Appendix B of the NTPv3 specification RFC1305, requesting
24 information about current state and/or changes in that state.
25 The same formats are used in NTPv4, although some of the
26 variables have changed and new ones added. The description on this
27 page is for the NTPv4 variables.
28 The program may be run either in interactive mode or controlled using
29 command line arguments.
30 Requests to read and write arbitrary
31 variables can be assembled, with raw and pretty-printed output
32 options being available.
33 The
34 ntpq
35 utility can also obtain and print a
36 list of peers in a common format by sending multiple queries to the
37 server.
39 If one or more request options is included on the command line
40 when
41 ntpq
42 is executed, each of the requests will be sent
43 to the NTP servers running on each of the hosts given as command
44 line arguments, or on localhost by default.
45 If no request options
46 are given,
47 ntpq
48 will attempt to read commands from the
49 standard input and execute these on the NTP server running on the
50 first host given on the command line, again defaulting to localhost
51 when no other host is specified.
52 The
53 ntpq
54 utility will prompt for
55 commands if the standard input is a terminal device.
57 The
58 ntpq
59 utility uses NTP mode 6 packets to communicate with the
60 NTP server, and hence can be used to query any compatible server on
61 the network which permits it.
62 Note that since NTP is a UDP protocol
63 this communication will be somewhat unreliable, especially over
64 large distances in terms of network topology.
65 The
66 ntpq
67 utility makes
68 one attempt to retransmit requests, and will time requests out if
69 the remote host is not heard from within a suitable timeout
70 time.
72 Specifying a
73 command line option other than
74 .Fl i
75 or
76 .Fl n
77 will
78 cause the specified query (queries) to be sent to the indicated
79 host(s) immediately.
80 Otherwise,
81 ntpq
82 will attempt to read
83 interactive format commands from the standard input.
84 .Ss "Internal Commands"
85 Interactive format commands consist of a keyword followed by zero
86 to four arguments.
87 Only enough characters of the full keyword to
88 uniquely identify the command need be typed.
90 A
91 number of interactive format commands are executed entirely within
92 the
93 ntpq
94 utility itself and do not result in NTP mode 6
95 requests being sent to a server.
96 These are described following.
97 .sp
98 .IR "? [command_keyword]"
99 A `\&?'
100 by itself will print a list of all the command
101 keywords known to this incarnation of
102 ntpq.
103 A
104 .Ql \&?
105 followed by a command keyword will print function and usage
106 information about the command.
107 This command is probably a better
108 source of information about
109 ntpq
110 than this manual
111 page.
112 .sp
113 .IR "addvars"
114 .Ar variable_name [=value] ...
115 .Xc
116 .sp
117 .IR "rmvars variable_name ..."
118 .sp
119 .IR "clearvars"
120 The data carried by NTP mode 6 messages consists of a list of
121 items of the form
122 .Ql variable_name=value ,
123 where the
124 .Ql =value
125 is ignored, and can be omitted,
126 in requests to the server to read variables.
127 The
128 ntpq
129 utility maintains an internal list in which data to be included in control
130 messages can be assembled, and sent using the
131 .Ic readlist
132 and
133 .Ic writelist
134 commands described below.
135 The
136 .Ic addvars
137 command allows variables and their optional values to be added to
138 the list.
139 If more than one variable is to be added, the list should
140 be comma-separated and not contain white space.
141 The
142 .Ic rmvars
143 command can be used to remove individual variables from the list,
144 while the
145 .Ic clearlist
146 command removes all variables from the
147 list.
148 .sp
149 .IR "authenticate [ yes | no ]"
150 Normally
151 ntpq
152 does not authenticate requests unless
153 they are write requests.
154 The command
155 .Ql authenticate yes
156 causes
157 ntpq
158 to send authentication with all requests it
159 makes.
160 Authenticated requests causes some servers to handle
161 requests slightly differently, and can occasionally melt the CPU in
162 fuzzballs if you turn authentication on before doing a
163 .Ic peer
164 display.
165 The command
166 .Ql authenticate
167 causes
168 ntpq
169 to display whether or not
170 ntpq
171 is currently autheinticating requests.
172 .sp
173 .IR "cooked"
174 Causes output from query commands to be "cooked", so that
175 variables which are recognized by
176 ntpq
177 will have their
178 values reformatted for human consumption.
179 Variables which
180 ntpq
181 thinks should have a decodable value but didn't are
182 marked with a trailing
183 .Ql \&? .
184 .@item debug [
185 .Cm more |
186 .Cm less |
187 .Cm off
188 ]
189 .Xc
190 With no argument, displays the current debug level.
191 Otherwise, the debug level is changed to the indicated level.
192 .sp
193 .IR "delay milliseconds"
194 Specify a time interval to be added to timestamps included in
195 requests which require authentication.
196 This is used to enable
197 (unreliable) server reconfiguration over long delay network paths
198 or between machines whose clocks are unsynchronized.
199 Actually the
200 server does not now require timestamps in authenticated requests,
201 so this command may be obsolete.
202 .sp
203 .IR "host hostname"
204 Set the host to which future queries will be sent.
205 Hostname may
206 be either a host name or a numeric address.
207 .sp
208 .IR "hostnames Cm yes | Cm no"
209 If
210 .Cm yes
211 is specified, host names are printed in
212 information displays.
213 If
214 .Cm no
215 is specified, numeric
216 addresses are printed instead.
217 The default is
218 .Cm yes ,
219 unless
220 modified using the command line
221 .Fl n
222 switch.
223 .sp
224 .IR "keyid keyid"
225 This command allows the specification of a key number to be
226 used to authenticate configuration requests.
227 This must correspond
228 to a key number the server has been configured to use for this
229 purpose.
230 .sp
231 .IR "ntpversion ["
232 .Cm 1 |
233 .Cm 2 |
234 .Cm 3 |
235 .Cm 4
236 ]
237 .Xc
238 Sets the NTP version number which
239 ntpq
240 claims in
241 packets.
242 Defaults to 3, Note that mode 6 control messages (and
243 modes, for that matter) didn't exist in NTP version 1.
244 There appear
245 to be no servers left which demand version 1.
246 With no argument, displays the current NTP version that will be used
247 when communicating with servers.
248 .sp
249 .IR "quit"
250 Exit
251 ntpq.
252 .sp
253 .IR "passwd"
254 This command prompts you to type in a password (which will not
255 be echoed) which will be used to authenticate configuration
256 requests.
257 The password must correspond to the key configured for
258 use by the NTP server for this purpose if such requests are to be
259 successful.
260 .sp
261 .IR "raw"
262 Causes all output from query commands is printed as received
263 from the remote server.
264 The only formating/interpretation done on
265 the data is to transform nonascii data into a printable (but barely
266 understandable) form.
267 .sp
268 .IR "timeout Ar milliseconds"
269 Specify a timeout period for responses to server queries.
270 The
271 default is about 5000 milliseconds.
272 Note that since
273 ntpq
274 retries each query once after a timeout, the total waiting time for
275 a timeout will be twice the timeout value set.
276 .br
278 .SH OPTIONS
279 .TP
280 .BR \-4 ", " \--ipv4
281 Force IPv4 DNS name resolution.
282 This option is a member of the ipv4 class of options.
283 .sp
284 Force DNS resolution of following host names on the command line
285 to the IPv4 namespace.
286 .TP
287 .BR \-6 ", " \--ipv6
288 Force IPv6 DNS name resolution.
289 This option is a member of the ipv4 class of options.
290 .sp
291 Force DNS resolution of following host names on the command line
292 to the IPv6 namespace.
293 .TP
294 .BR \-c " \fIcmd\fP, " \--command "=" \fIcmd\fP
295 run a command and exit.
296 This option may appear an unlimited number of times.
297 .sp
298 The following argument is interpreted as an interactive format command
299 and is added to the list of commands to be executed on the specified
300 host(s).
301 .TP
302 .BR \-d ", " \--debug-level
303 Increase output debug message level.
304 This option may appear an unlimited number of times.
305 .sp
306 Increase the debugging message output level.
307 .TP
308 .BR \-D " \fIstring\fP, " \--set-debug-level "=" \fIstring\fP
309 Set the output debug message level.
310 This option may appear an unlimited number of times.
311 .sp
312 Set the output debugging level. Can be supplied multiple times,
313 but each overrides the previous value(s).
314 .TP
315 .BR \-p ", " \--peers
316 Print a list of the peers.
317 This option must not appear in combination with any of the following options:
318 interactive.
319 .sp
320 Print a list of the peers known to the server as well as a summary
321 of their state. This is equivalent to the 'peers' interactive command.
322 .TP
323 .BR \-i ", " \--interactive
324 Force ntpq to operate in interactive mode.
325 This option must not appear in combination with any of the following options:
326 command, peers.
327 .sp
328 Force ntpq to operate in interactive mode. Prompts will be written
329 to the standard output and commands read from the standard input.
330 .TP
331 .BR \-n ", " \--numeric
332 numeric host addresses.
333 .sp
334 Output all host addresses in dotted-quad numeric format rather than
335 converting to the canonical host names.
336 .TP
337 .BR \-? , " \--help"
338 Display usage information and exit.
339 .TP
340 .BR \-! , " \--more-help"
341 Extended usage information passed thru pager.
342 .TP
343 .BR \-> " [\fIrcfile\fP]," " \--save-opts" "[=\fIrcfile\fP]"
344 Save the option state to \fIrcfile\fP. The default is the \fIlast\fP
345 configuration file listed in the \fBOPTION PRESETS\fP section, below.
346 .TP
347 .BR \-< " \fIrcfile\fP," " \--load-opts" "=\fIrcfile\fP," " \--no-load-opts"
348 Load options from \fIrcfile\fP.
349 The \fIno-load-opts\fP form will disable the loading
350 of earlier RC/INI files. \fI--no-load-opts\fP is handled early,
351 out of order.
352 .TP
353 .BR \-v " [{\fIv|c|n\fP}]," " \--version" "[=\fI{v|c|n}\fP]"
354 Output version of program and exit. The default mode is `v', a simple
355 version. The `c' mode will print copyright information and `n' will
356 print the full copyright notice.
357 .SH OPTION PRESETS
358 Any option that is not marked as \fInot presettable\fP may be preset
359 by loading values from configuration ("RC" or ".INI") file(s) and values from
360 environment variables named:
361 .nf
362 \fBNTPQ_<option-name>\fP or \fBNTPQ\fP
363 .fi
364 .aj
365 The environmental presets take precedence (are processed later than)
366 the configuration files.
367 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
368 If any of these are directories, then the file \fI.ntprc\fP
369 is searched for within those directories.
370 .SH AUTHOR
371 David L. Mills and/or others
372 .br
373 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
375 .PP
376 .nf
377 .na
378 see /usr/share/doc/html/ntp/copyright.html
379 .fi
380 .ad
381 .PP
382 This manual page was \fIAutoGen\fP-erated from the \fBntpq\fP
383 option definitions.