1: /* -*- Mode: Text -*- */
2:
3: autogen definitions options;
4:
5: #include copyright.def
6: #include homerc.def
7: #include autogen-version.def
8:
9: prog-name = "ntpq";
10: prog-title = "standard NTP query program";
11: argument = '[ host ...]';
12:
13: test-main;
14:
15: flag = {
16: name = ipv4;
17: flags-cant = ipv6;
18: value = 4;
19: descrip = "Force IPv4 DNS name resolution";
20: doc = <<- _EndOfDoc_
21: Force DNS resolution of following host names on the command line
22: to the IPv4 namespace.
23: _EndOfDoc_;
24: };
25:
26: flag = {
27: name = ipv6;
28: flags-cant = ipv4;
29: value = 6;
30: descrip = "Force IPv6 DNS name resolution";
31: doc = <<- _EndOfDoc_
32: Force DNS resolution of following host names on the command line
33: to the IPv6 namespace.
34: _EndOfDoc_;
35: };
36:
37: flag = {
38: name = command;
39: value = c;
40: arg-type = string;
41: descrip = "run a command and exit";
42: max = NOLIMIT;
43: arg-name = cmd;
44: call-proc = ntpq_custom_opt_handler;
45: doc = <<- _EndOfDoc_
46: The following argument is interpreted as an interactive format command
47: and is added to the list of commands to be executed on the specified
48: host(s).
49: _EndOfDoc_;
50: };
51:
52: #include debug-opt.def
53:
54: flag = {
55: name = peers;
56: value = p;
57: descrip = "Print a list of the peers";
58: flags-cant = interactive;
59: call-proc = ntpq_custom_opt_handler;
60: doc = <<- _EndOfDoc_
61: Print a list of the peers known to the server as well as a summary
62: of their state. This is equivalent to the 'peers' interactive command.
63: _EndOfDoc_;
64: };
65:
66: flag = {
67: name = interactive;
68: value = i;
69: flags-cant = command, peers;
70: descrip = "Force ntpq to operate in interactive mode";
71: doc = <<- _EndOfDoc_
72: Force ntpq to operate in interactive mode. Prompts will be written
73: to the standard output and commands read from the standard input.
74: _EndOfDoc_;
75: };
76:
77: flag = {
78: name = numeric;
79: value = n;
80: descrip = "numeric host addresses";
81: doc = <<- _EndOfDoc_
82: Output all host addresses in dotted-quad numeric format rather than
83: converting to the canonical host names.
84: _EndOfDoc_;
85: };
86:
87: flag = {
88: name = old-rv;
89: descrip = "Always output status line with readvar";
90: doc = <<- _EndOfDoc_
91: By default, ntpq now suppresses the associd=... line that
92: precedes the output of "readvar" (alias "rv") when a single
93: variable is requested, such as ntpq -c "rv 0 offset". This
94: option causes ntpq to include both lines of output for a
95: single-variable readvar. Using an environment variable to
96: preset this option in a script will enable both older and
97: newer ntpq to behave identically in this regard.
98: _EndOfDoc_;
99: };
100:
101: detail = <<- _END_DETAIL
102: The
103: [= prog-name =]
104: utility program is used to query NTP servers which
105: implement the standard NTP mode 6 control message formats defined
106: in Appendix B of the NTPv3 specification RFC1305, requesting
107: information about current state and/or changes in that state.
108: The same formats are used in NTPv4, although some of the
109: variables have changed and new ones added.
110: _END_DETAIL;
111:
112: prog-man-descrip = <<- _END_PROG_MAN_DESCRIP
113: The
114: [= prog-name =]
115: utility program is used to query NTP servers which
116: implement the standard NTP mode 6 control message formats defined
117: in Appendix B of the NTPv3 specification RFC1305, requesting
118: information about current state and/or changes in that state.
119: The same formats are used in NTPv4, although some of the
120: variables have changed and new ones added. The description on this
121: page is for the NTPv4 variables.
122: The program may be run either in interactive mode or controlled using
123: command line arguments.
124: Requests to read and write arbitrary
125: variables can be assembled, with raw and pretty-printed output
126: options being available.
127: The
128: [= prog-name =]
129: utility can also obtain and print a
130: list of peers in a common format by sending multiple queries to the
131: server.
132:
133: If one or more request options is included on the command line
134: when
135: [= prog-name =]
136: is executed, each of the requests will be sent
137: to the NTP servers running on each of the hosts given as command
138: line arguments, or on localhost by default.
139: If no request options
140: are given,
141: [= prog-name =]
142: will attempt to read commands from the
143: standard input and execute these on the NTP server running on the
144: first host given on the command line, again defaulting to localhost
145: when no other host is specified.
146: The
147: [= prog-name =]
148: utility will prompt for
149: commands if the standard input is a terminal device.
150:
151: The
152: [= prog-name =]
153: utility uses NTP mode 6 packets to communicate with the
154: NTP server, and hence can be used to query any compatible server on
155: the network which permits it.
156: Note that since NTP is a UDP protocol
157: this communication will be somewhat unreliable, especially over
158: large distances in terms of network topology.
159: The
160: [= prog-name =]
161: utility makes
162: one attempt to retransmit requests, and will time requests out if
163: the remote host is not heard from within a suitable timeout
164: time.
165:
166: Specifying a
167: command line option other than
168: .Fl i
169: or
170: .Fl n
171: will
172: cause the specified query (queries) to be sent to the indicated
173: host(s) immediately.
174: Otherwise,
175: [= prog-name =]
176: will attempt to read
177: interactive format commands from the standard input.
178: .Ss "Internal Commands"
179: Interactive format commands consist of a keyword followed by zero
180: to four arguments.
181: Only enough characters of the full keyword to
182: uniquely identify the command need be typed.
183:
184: A
185: number of interactive format commands are executed entirely within
186: the
187: [= prog-name =]
188: utility itself and do not result in NTP mode 6
189: requests being sent to a server.
190: These are described following.
191: @table @code
192: @item ? [command_keyword]
193: @itemx help [command_keyword]
194: A
195: .Ql \&?
196: by itself will print a list of all the command
197: keywords known to this incarnation of
198: [= prog-name =] .
199: A
200: .Ql \&?
201: followed by a command keyword will print function and usage
202: information about the command.
203: This command is probably a better
204: source of information about
205: [= prog-name =]
206: than this manual
207: page.
208: @item addvars
209: .Ar variable_name [=value] ...
210: .Xc
211: @item rmvars variable_name ...
212: @item clearvars
213: The data carried by NTP mode 6 messages consists of a list of
214: items of the form
215: .Ql variable_name=value ,
216: where the
217: .Ql =value
218: is ignored, and can be omitted,
219: in requests to the server to read variables.
220: The
221: [= prog-name =]
222: utility maintains an internal list in which data to be included in control
223: messages can be assembled, and sent using the
224: .Ic readlist
225: and
226: .Ic writelist
227: commands described below.
228: The
229: .Ic addvars
230: command allows variables and their optional values to be added to
231: the list.
232: If more than one variable is to be added, the list should
233: be comma-separated and not contain white space.
234: The
235: .Ic rmvars
236: command can be used to remove individual variables from the list,
237: while the
238: .Ic clearlist
239: command removes all variables from the
240: list.
241: @item authenticate [ yes | no ]
242: Normally
243: [= prog-name =]
244: does not authenticate requests unless
245: they are write requests.
246: The command
247: .Ql authenticate yes
248: causes
249: [= prog-name =]
250: to send authentication with all requests it
251: makes.
252: Authenticated requests causes some servers to handle
253: requests slightly differently, and can occasionally melt the CPU in
254: fuzzballs if you turn authentication on before doing a
255: .Ic peer
256: display.
257: The command
258: .Ql authenticate
259: causes
260: [= prog-name =]
261: to display whether or not
262: [= prog-name =]
263: is currently autheinticating requests.
264: @item cooked
265: Causes output from query commands to be "cooked", so that
266: variables which are recognized by
267: [= prog-name =]
268: will have their
269: values reformatted for human consumption.
270: Variables which
271: [= prog-name =]
272: thinks should have a decodable value but didn't are
273: marked with a trailing
274: .Ql \&? .
275: .@item debug [
276: .Cm more |
277: .Cm less |
278: .Cm off
279: ]
280: .Xc
281: With no argument, displays the current debug level.
282: Otherwise, the debug level is changed to the indicated level.
283: @item delay milliseconds
284: Specify a time interval to be added to timestamps included in
285: requests which require authentication.
286: This is used to enable
287: (unreliable) server reconfiguration over long delay network paths
288: or between machines whose clocks are unsynchronized.
289: Actually the
290: server does not now require timestamps in authenticated requests,
291: so this command may be obsolete.
292: @item host hostname
293: Set the host to which future queries will be sent.
294: Hostname may
295: be either a host name or a numeric address.
296: @item hostnames Cm yes | Cm no
297: If
298: .Cm yes
299: is specified, host names are printed in
300: information displays.
301: If
302: .Cm no
303: is specified, numeric
304: addresses are printed instead.
305: The default is
306: .Cm yes ,
307: unless
308: modified using the command line
309: .Fl n
310: switch.
311: @item keyid keyid
312: This command allows the specification of a key number to be
313: used to authenticate configuration requests.
314: This must correspond
315: to a key number the server has been configured to use for this
316: purpose.
317: @item ntpversion [
318: .Cm 1 |
319: .Cm 2 |
320: .Cm 3 |
321: .Cm 4
322: ]
323: .Xc
324: Sets the NTP version number which
325: [= prog-name =]
326: claims in
327: packets.
328: Defaults to 3, Note that mode 6 control messages (and
329: modes, for that matter) didn't exist in NTP version 1.
330: There appear
331: to be no servers left which demand version 1.
332: With no argument, displays the current NTP version that will be used
333: when communicating with servers.
334: @item quit
335: Exit
336: [= prog-name =] .
337: @item passwd
338: This command prompts you to type in a password (which will not
339: be echoed) which will be used to authenticate configuration
340: requests.
341: The password must correspond to the key configured for
342: use by the NTP server for this purpose if such requests are to be
343: successful.
344: @item raw
345: Causes all output from query commands is printed as received
346: from the remote server.
347: The only formating/interpretation done on
348: the data is to transform nonascii data into a printable (but barely
349: understandable) form.
350: @item timeout Ar milliseconds
351: Specify a timeout period for responses to server queries.
352: The
353: default is about 5000 milliseconds.
354: Note that since
355: [= prog-name =]
356: retries each query once after a timeout, the total waiting time for
357: a timeout will be twice the timeout value set.
358: @end table
359:
360: _END_PROG_MAN_DESCRIP;
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to ntpq-opts.def CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / ntp / ntpq