PageRenderTime 34ms CodeModel.GetById 12ms app.highlight 17ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/ntp/ntpq/ntpq-opts.def

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