1.\"
| 1.\"
|
2.\" $FreeBSD: head/usr.sbin/ntp/doc/ntpq.8 82501 2001-08-29 14:50:56Z sheldonh $
| 2.\" $FreeBSD: head/usr.sbin/ntp/doc/ntpq.8 89625 2002-01-21 20:12:02Z roberto $
|
3.\"
4.Dd January 7, 2000
5.Dt NTPQ 8
6.Os
7.Sh NAME
8.Nm ntpq
9.Nd standard NTP query program
10.Sh SYNOPSIS
11.Nm
12.Op Fl inp
13.Op Fl c Ar command
14.Op Ar host ...
15.Sh DESCRIPTION
16The
17.Nm
18utility program is used to query NTP servers
19which implement the recommended NTP mode 6 control message format
20about current state and to request changes in that state.
21The
22program may be run either in interactive mode or controlled using
23command line arguments.
24Requests to read and write arbitrary
25variables can be assembled, with raw and pretty-printed output
26options being available.
27.Nm
28can also obtain and print a
29list of peers in a common format by sending multiple queries to the
30server.
31.Pp
32If one or more request options is included on the command line
33when
34.Nm
35is executed, each of the requests will be sent
36to the NTP servers running on each of the hosts given as command
37line arguments, or on localhost by default.
38If no request options
39are given,
40.Nm
41will attempt to read commands from the
42standard input and execute these on the NTP server running on the
43first host given on the command line, again defaulting to localhost
44when no other host is specified.
45.Nm
46will prompt for
47commands if the standard input is a terminal device.
48.Pp
49.Nm
50uses NTP mode 6 packets to communicate with the
51NTP server, and hence can be used to query any compatible server on
52the network which permits it.
53Note that since NTP is a UDP protocol
54this communication will be somewhat unreliable, especially over
55large distances in terms of network topology.
56.Nm
57makes
58one attempt to retransmit requests, and will time requests out if
59the remote host is not heard from within a suitable timeout
60time.
61.Pp
62For examples and usage, see the
63.Qq "NTP Debugging Techniques"
64page
65(available as part of the HTML documentation
66provided in
67.Pa /usr/share/doc/ntp ) .
68.Pp
69The following options are available:
70.Bl -tag -width indent
71.It Fl c
72The following argument is interpreted as an interactive format
73command and is added to the list of commands to be executed on the
74specified host(s).
75Multiple
76.Fl c
77options may be given.
78.It Fl i
79Force
80.Nm
81to operate in interactive mode.
82Prompts
83will be written to the standard output and commands read from the
84standard input.
85.It Fl n
86Output all host addresses in dotted-quad numeric format rather
87than converting to the canonical host names.
88.It Fl p
89Print a list of the peers known to the server as well as a
90summary of their state.
91This is equivalent to the
92.Ic peers
93interactive command.
94.El
95.Pp
96Specifying a
97command line option other than
98.Fl i
99or
100.Fl n
101will
102cause the specified query (queries) to be sent to the indicated
103host(s) immediately.
104Otherwise,
105.Nm
106will attempt to read
107interactive format commands from the standard input.
108.Ss "Internal Commands"
109Interactive format commands consist of a keyword followed by zero
110to four arguments.
111Only enough characters of the full keyword to
112uniquely identify the command need be typed.
113The output of a
114command is normally sent to the standard output, but optionally the
115output of individual commands may be sent to a file by appending a
| 3.\"
4.Dd January 7, 2000
5.Dt NTPQ 8
6.Os
7.Sh NAME
8.Nm ntpq
9.Nd standard NTP query program
10.Sh SYNOPSIS
11.Nm
12.Op Fl inp
13.Op Fl c Ar command
14.Op Ar host ...
15.Sh DESCRIPTION
16The
17.Nm
18utility program is used to query NTP servers
19which implement the recommended NTP mode 6 control message format
20about current state and to request changes in that state.
21The
22program may be run either in interactive mode or controlled using
23command line arguments.
24Requests to read and write arbitrary
25variables can be assembled, with raw and pretty-printed output
26options being available.
27.Nm
28can also obtain and print a
29list of peers in a common format by sending multiple queries to the
30server.
31.Pp
32If one or more request options is included on the command line
33when
34.Nm
35is executed, each of the requests will be sent
36to the NTP servers running on each of the hosts given as command
37line arguments, or on localhost by default.
38If no request options
39are given,
40.Nm
41will attempt to read commands from the
42standard input and execute these on the NTP server running on the
43first host given on the command line, again defaulting to localhost
44when no other host is specified.
45.Nm
46will prompt for
47commands if the standard input is a terminal device.
48.Pp
49.Nm
50uses NTP mode 6 packets to communicate with the
51NTP server, and hence can be used to query any compatible server on
52the network which permits it.
53Note that since NTP is a UDP protocol
54this communication will be somewhat unreliable, especially over
55large distances in terms of network topology.
56.Nm
57makes
58one attempt to retransmit requests, and will time requests out if
59the remote host is not heard from within a suitable timeout
60time.
61.Pp
62For examples and usage, see the
63.Qq "NTP Debugging Techniques"
64page
65(available as part of the HTML documentation
66provided in
67.Pa /usr/share/doc/ntp ) .
68.Pp
69The following options are available:
70.Bl -tag -width indent
71.It Fl c
72The following argument is interpreted as an interactive format
73command and is added to the list of commands to be executed on the
74specified host(s).
75Multiple
76.Fl c
77options may be given.
78.It Fl i
79Force
80.Nm
81to operate in interactive mode.
82Prompts
83will be written to the standard output and commands read from the
84standard input.
85.It Fl n
86Output all host addresses in dotted-quad numeric format rather
87than converting to the canonical host names.
88.It Fl p
89Print a list of the peers known to the server as well as a
90summary of their state.
91This is equivalent to the
92.Ic peers
93interactive command.
94.El
95.Pp
96Specifying a
97command line option other than
98.Fl i
99or
100.Fl n
101will
102cause the specified query (queries) to be sent to the indicated
103host(s) immediately.
104Otherwise,
105.Nm
106will attempt to read
107interactive format commands from the standard input.
108.Ss "Internal Commands"
109Interactive format commands consist of a keyword followed by zero
110to four arguments.
111Only enough characters of the full keyword to
112uniquely identify the command need be typed.
113The output of a
114command is normally sent to the standard output, but optionally the
115output of individual commands may be sent to a file by appending a
|
116.Ql \&< ,
| 116.Ql \&> ,
|
117followed by a file name, to the command line.
118A
119number of interactive format commands are executed entirely within
120the
121.Nm
122program itself and do not result in NTP mode 6
123requests being sent to a server.
124These are described following.
125.Bl -tag -width indent
126.It Ic \&? Op Ar command_keyword
127.It Ic help Op Ar command_keyword
128A
129.Ql \&?
130by itself will print a list of all the command
131keywords known to this incarnation of
132.Nm .
133A
134.Ql \&?
135followed by a command keyword will print function and usage
136information about the command.
137This command is probably a better
138source of information about
139.Nm
140than this manual
141page.
142.It Xo Ic addvars
143.Ar variable_name Ns Op = Ns Ar value ...
144.Xc
145.It Ic rmvars Ar variable_name ...
146.It Ic clearvars
147The data carried by NTP mode 6 messages consists of a list of
148items of the form
149.Ql variable_name=value ,
150where the
151.Ql =value
152is ignored, and can be omitted,
153in requests to the server to read variables.
154.Nm
155maintains an internal list in which data to be included in control
156messages can be assembled, and sent using the
157.Ic readlist
158and
159.Ic writelist
160commands described below.
161The
162.Ic addvars
163command allows variables and their optional values to be added to
164the list.
165If more than one variable is to be added, the list should
166be comma-separated and not contain white space.
167The
168.Ic rmvars
169command can be used to remove individual variables from the list,
170while the
171.Ic clearlist
172command removes all variables from the
173list.
174.It Ic authenticate Cm yes | Cm no
175Normally
176.Nm
177does not authenticate requests unless
178they are write requests.
179The command
180.Ql authenticate yes
181causes
182.Nm
183to send authentication with all requests it
184makes.
185Authenticated requests causes some servers to handle
186requests slightly differently, and can occasionally melt the CPU in
187fuzzballs if you turn authentication on before doing a
188.Ic peer
189display.
190.It Ic cooked
191Causes output from query commands to be "cooked", so that
192variables which are recognized by
193.Nm
194will have their
195values reformatted for human consumption.
196Variables which
197.Nm
198thinks should have a decodable value but didn't are
199marked with a trailing
200.Ql \&? .
201.It Xo Ic debug
202.Cm more |
203.Cm less |
204.Cm off
205.Xc
206Turns internal query program debugging on and off.
207.It Ic delay Ar milliseconds
208Specify a time interval to be added to timestamps included in
209requests which require authentication.
210This is used to enable
211(unreliable) server reconfiguration over long delay network paths
212or between machines whose clocks are unsynchronized.
213Actually the
214server does not now require timestamps in authenticated requests,
215so this command may be obsolete.
216.It Ic host Ar hostname
217Set the host to which future queries will be sent.
218Hostname may
219be either a host name or a numeric address.
220.It Ic hostnames Cm yes | Cm no
221If
222.Cm yes
223is specified, host names are printed in
224information displays.
225If
226.Cm no
227is specified, numeric
228addresses are printed instead.
229The default is
230.Cm yes ,
231unless
232modified using the command line
233.Fl n
234switch.
235.It Ic keyid Ar keyid
236This command allows the specification of a key number to be
237used to authenticate configuration requests.
238This must correspond
239to a key number the server has been configured to use for this
240purpose.
241.It Xo Ic ntpversion
242.Cm 1 |
243.Cm 2 |
244.Cm 3 |
245.Cm 4
246.Xc
247Sets the NTP version number which
248.Nm
249claims in
250packets.
251Defaults to 3, Note that mode 6 control messages (and
252modes, for that matter) didn't exist in NTP version 1.
253There appear
254to be no servers left which demand version 1.
255.It Ic quit
256Exit
257.Nm .
258.It Ic passwd
259This command prompts you to type in a password (which will not
260be echoed) which will be used to authenticate configuration
261requests.
262The password must correspond to the key configured for
263use by the NTP server for this purpose if such requests are to be
264successful.
265.It Ic raw
266Causes all output from query commands is printed as received
267from the remote server.
268The only formating/interpretation done on
269the data is to transform nonascii data into a printable (but barely
270understandable) form.
271.It Ic timeout Ar milliseconds
272Specify a timeout period for responses to server queries.
273The
274default is about 5000 milliseconds.
275Note that since
276.Nm
277retries each query once after a timeout, the total waiting time for
278a timeout will be twice the timeout value set.
279.El
280.Ss Control Message Commands
281Each peer known to an NTP server has a 16 bit integer association
282identifier assigned to it.
283NTP control messages which carry peer
284variables must identify the peer the values correspond to by
285including its association ID.
286An association ID of 0 is special,
287and indicates the variables are system variables, whose names are
288drawn from a separate name space.
289.Pp
290Control message commands result in one or more NTP mode 6
291messages being sent to the server, and cause the data returned to
292be printed in some format.
293Most commands currently implemented send
294a single message and expect a single response.
295The current
296exceptions are the peers command, which will send a preprogrammed
297series of messages to obtain the data it needs, and the mreadlist
298and mreadvar commands, which will iterate over a range of
299associations.
300.Bl -tag -width indent
301.It Ic associations
302Obtains and prints a list of association identifiers and peer
303statuses for in-spec peers of the server being queried.
304The list is
305printed in columns.
306The first of these is an index numbering the
307associations from 1 for internal use, the second the actual
308association identifier returned by the server and the third the
309status word for the peer.
310This is followed by a number of columns
311containing data decoded from the status word.
312See the peers command
313for a decode of the
314.Sq condition
315field.
316Note that the data
317returned by the
318.Ic associations
319command is cached internally
320in
321.Xr ntpq 8 .
322The index is then of use when dealing with stupid
323servers which use association identifiers which are hard for humans
324to type, in that for any subsequent commands which require an
| 117followed by a file name, to the command line.
118A
119number of interactive format commands are executed entirely within
120the
121.Nm
122program itself and do not result in NTP mode 6
123requests being sent to a server.
124These are described following.
125.Bl -tag -width indent
126.It Ic \&? Op Ar command_keyword
127.It Ic help Op Ar command_keyword
128A
129.Ql \&?
130by itself will print a list of all the command
131keywords known to this incarnation of
132.Nm .
133A
134.Ql \&?
135followed by a command keyword will print function and usage
136information about the command.
137This command is probably a better
138source of information about
139.Nm
140than this manual
141page.
142.It Xo Ic addvars
143.Ar variable_name Ns Op = Ns Ar value ...
144.Xc
145.It Ic rmvars Ar variable_name ...
146.It Ic clearvars
147The data carried by NTP mode 6 messages consists of a list of
148items of the form
149.Ql variable_name=value ,
150where the
151.Ql =value
152is ignored, and can be omitted,
153in requests to the server to read variables.
154.Nm
155maintains an internal list in which data to be included in control
156messages can be assembled, and sent using the
157.Ic readlist
158and
159.Ic writelist
160commands described below.
161The
162.Ic addvars
163command allows variables and their optional values to be added to
164the list.
165If more than one variable is to be added, the list should
166be comma-separated and not contain white space.
167The
168.Ic rmvars
169command can be used to remove individual variables from the list,
170while the
171.Ic clearlist
172command removes all variables from the
173list.
174.It Ic authenticate Cm yes | Cm no
175Normally
176.Nm
177does not authenticate requests unless
178they are write requests.
179The command
180.Ql authenticate yes
181causes
182.Nm
183to send authentication with all requests it
184makes.
185Authenticated requests causes some servers to handle
186requests slightly differently, and can occasionally melt the CPU in
187fuzzballs if you turn authentication on before doing a
188.Ic peer
189display.
190.It Ic cooked
191Causes output from query commands to be "cooked", so that
192variables which are recognized by
193.Nm
194will have their
195values reformatted for human consumption.
196Variables which
197.Nm
198thinks should have a decodable value but didn't are
199marked with a trailing
200.Ql \&? .
201.It Xo Ic debug
202.Cm more |
203.Cm less |
204.Cm off
205.Xc
206Turns internal query program debugging on and off.
207.It Ic delay Ar milliseconds
208Specify a time interval to be added to timestamps included in
209requests which require authentication.
210This is used to enable
211(unreliable) server reconfiguration over long delay network paths
212or between machines whose clocks are unsynchronized.
213Actually the
214server does not now require timestamps in authenticated requests,
215so this command may be obsolete.
216.It Ic host Ar hostname
217Set the host to which future queries will be sent.
218Hostname may
219be either a host name or a numeric address.
220.It Ic hostnames Cm yes | Cm no
221If
222.Cm yes
223is specified, host names are printed in
224information displays.
225If
226.Cm no
227is specified, numeric
228addresses are printed instead.
229The default is
230.Cm yes ,
231unless
232modified using the command line
233.Fl n
234switch.
235.It Ic keyid Ar keyid
236This command allows the specification of a key number to be
237used to authenticate configuration requests.
238This must correspond
239to a key number the server has been configured to use for this
240purpose.
241.It Xo Ic ntpversion
242.Cm 1 |
243.Cm 2 |
244.Cm 3 |
245.Cm 4
246.Xc
247Sets the NTP version number which
248.Nm
249claims in
250packets.
251Defaults to 3, Note that mode 6 control messages (and
252modes, for that matter) didn't exist in NTP version 1.
253There appear
254to be no servers left which demand version 1.
255.It Ic quit
256Exit
257.Nm .
258.It Ic passwd
259This command prompts you to type in a password (which will not
260be echoed) which will be used to authenticate configuration
261requests.
262The password must correspond to the key configured for
263use by the NTP server for this purpose if such requests are to be
264successful.
265.It Ic raw
266Causes all output from query commands is printed as received
267from the remote server.
268The only formating/interpretation done on
269the data is to transform nonascii data into a printable (but barely
270understandable) form.
271.It Ic timeout Ar milliseconds
272Specify a timeout period for responses to server queries.
273The
274default is about 5000 milliseconds.
275Note that since
276.Nm
277retries each query once after a timeout, the total waiting time for
278a timeout will be twice the timeout value set.
279.El
280.Ss Control Message Commands
281Each peer known to an NTP server has a 16 bit integer association
282identifier assigned to it.
283NTP control messages which carry peer
284variables must identify the peer the values correspond to by
285including its association ID.
286An association ID of 0 is special,
287and indicates the variables are system variables, whose names are
288drawn from a separate name space.
289.Pp
290Control message commands result in one or more NTP mode 6
291messages being sent to the server, and cause the data returned to
292be printed in some format.
293Most commands currently implemented send
294a single message and expect a single response.
295The current
296exceptions are the peers command, which will send a preprogrammed
297series of messages to obtain the data it needs, and the mreadlist
298and mreadvar commands, which will iterate over a range of
299associations.
300.Bl -tag -width indent
301.It Ic associations
302Obtains and prints a list of association identifiers and peer
303statuses for in-spec peers of the server being queried.
304The list is
305printed in columns.
306The first of these is an index numbering the
307associations from 1 for internal use, the second the actual
308association identifier returned by the server and the third the
309status word for the peer.
310This is followed by a number of columns
311containing data decoded from the status word.
312See the peers command
313for a decode of the
314.Sq condition
315field.
316Note that the data
317returned by the
318.Ic associations
319command is cached internally
320in
321.Xr ntpq 8 .
322The index is then of use when dealing with stupid
323servers which use association identifiers which are hard for humans
324to type, in that for any subsequent commands which require an
|
325association identifier as an argument, the form and index may be
| 325association identifier as an argument, the form of index may be
|
326used as an alternative.
327.It Xo Ic clockvar Op Ar assocID
328.Oo
329.Ar variable_name Ns Op = Ns Ar value ...
330.Oc
331.Ar ...
332.Xc
333.It Xo Ic cv Op Ar assocID
334.Oo
335.Ar variable_name Ns Op = Ns Ar value ...
336.Oc
337.Ar ...
338.Xc
339Requests that a list of the server's clock variables be sent.
340Servers which have a radio clock or other external synchronization
341will respond positively to this.
342If the association identifier is
343omitted or zero the request is for the variables of the
344.Sq system clock
345and will generally get a positive response from all
346servers with a clock.
347If the server treats clocks as pseudo-peers,
348and hence can possibly have more than one clock connected at once,
349referencing the appropriate peer association ID will show the
350variables of a particular clock.
351Omitting the variable list will
352cause the server to return a default variable display.
353.It Ic lassociations
354Obtains and prints a list of association identifiers and peer
355statuses for all associations for which the server is maintaining
356state.
357This command differs from the
358.Ic associations
359command
360only for servers which retain state for out-of-spec client
361associations (i.e., fuzzballs).
362Such associations are normally
363omitted from the display when the
364.Ic associations
365command is
366used, but are included in the output of
367.Ic lassociations .
368.It Ic lpassociations
369Print data for all associations, including out-of-spec client
370associations, from the internally cached list of associations.
371This
372command differs from
373.Ic passociations
374only when dealing with
375fuzzballs.
376.It Ic lpeers
377Like R peers, except a summary of all associations for which
378the server is maintaining state is printed.
379This can produce a much
380longer list of peers from fuzzball servers.
381.It Ic mreadlist Ar assocID Ar assocID
382.It Ic mrl Ar assocID Ar assocID
383Like the
384.Ic readlist
385command, except the query is done
386for each of a range of (nonzero) association IDs.
387This range is
388determined from the association list cached by the most recent
389.Ic associations
390command.
391.It Xo Ic mreadvar Ar assocID Ar assocID
392.Oo
393.Ar variable_name Ns Op = Ns Ar value ...
394.Oc
395.Xc
396.It Xo Ic mrv Ar assocID Ar assocID
397.Oo
398.Ar variable_name Ns Op = Ns Ar value ...
399.Oc
400.Xc
401Like the
402.Ic readvar
403command, except the query is done for
404each of a range of (nonzero) association IDs.
405This range is
406determined from the association list cached by the most recent
407.Ic associations
408command.
409.It Ic opeers
410An old form of the
411.Ic peers
412command with the reference ID
413replaced by the local interface address.
| 326used as an alternative.
327.It Xo Ic clockvar Op Ar assocID
328.Oo
329.Ar variable_name Ns Op = Ns Ar value ...
330.Oc
331.Ar ...
332.Xc
333.It Xo Ic cv Op Ar assocID
334.Oo
335.Ar variable_name Ns Op = Ns Ar value ...
336.Oc
337.Ar ...
338.Xc
339Requests that a list of the server's clock variables be sent.
340Servers which have a radio clock or other external synchronization
341will respond positively to this.
342If the association identifier is
343omitted or zero the request is for the variables of the
344.Sq system clock
345and will generally get a positive response from all
346servers with a clock.
347If the server treats clocks as pseudo-peers,
348and hence can possibly have more than one clock connected at once,
349referencing the appropriate peer association ID will show the
350variables of a particular clock.
351Omitting the variable list will
352cause the server to return a default variable display.
353.It Ic lassociations
354Obtains and prints a list of association identifiers and peer
355statuses for all associations for which the server is maintaining
356state.
357This command differs from the
358.Ic associations
359command
360only for servers which retain state for out-of-spec client
361associations (i.e., fuzzballs).
362Such associations are normally
363omitted from the display when the
364.Ic associations
365command is
366used, but are included in the output of
367.Ic lassociations .
368.It Ic lpassociations
369Print data for all associations, including out-of-spec client
370associations, from the internally cached list of associations.
371This
372command differs from
373.Ic passociations
374only when dealing with
375fuzzballs.
376.It Ic lpeers
377Like R peers, except a summary of all associations for which
378the server is maintaining state is printed.
379This can produce a much
380longer list of peers from fuzzball servers.
381.It Ic mreadlist Ar assocID Ar assocID
382.It Ic mrl Ar assocID Ar assocID
383Like the
384.Ic readlist
385command, except the query is done
386for each of a range of (nonzero) association IDs.
387This range is
388determined from the association list cached by the most recent
389.Ic associations
390command.
391.It Xo Ic mreadvar Ar assocID Ar assocID
392.Oo
393.Ar variable_name Ns Op = Ns Ar value ...
394.Oc
395.Xc
396.It Xo Ic mrv Ar assocID Ar assocID
397.Oo
398.Ar variable_name Ns Op = Ns Ar value ...
399.Oc
400.Xc
401Like the
402.Ic readvar
403command, except the query is done for
404each of a range of (nonzero) association IDs.
405This range is
406determined from the association list cached by the most recent
407.Ic associations
408command.
409.It Ic opeers
410An old form of the
411.Ic peers
412command with the reference ID
413replaced by the local interface address.
|
414.It Ic passocations
| 414.It Ic passociations
|
415Displays association data concerning in-spec peers from the
416internally cached list of associations.
417This command performs
418identically to the
419.Ic associations
420except that it displays
421the internally stored data rather than making a new query.
422.It Ic peers
423Obtains a current list peers of the server, along with a
424summary of each peer's state.
425Summary information includes the
426address of the remote peer, the reference ID (0.0.0.0 if this is
427unknown), the stratum of the remote peer, the type of the peer
428(local, unicast, multicast or broadcast), when the last packet was
429received, the polling interval, in seconds, the reachability
430register, in octal, and the current estimated delay, offset and
431dispersion of the peer, all in milliseconds.
432The character in the left margin indicates the fate of this
433peer in the clock selection process.
434Following is a list of these
435characters, the pigeon used in the
436.Ic rv
437command, and a short
438explanation of the condition revealed.
439.Bl -tag -width indent
440.It space
441.Pq reject
442The peer is discarded as unreachable, synchronized to this
443server (synch loop) or outrageous synchronization distance.
444.It x
445.Pq falsetick
446The peer is discarded by the intersection algorithm as a
447falseticker.
448.It \&.
449.Pq excess
450The peer is discarded as not among the first ten peers sorted
451by synchronization distance and so is probably a poor candidate for
452further consideration.
453.It \&-
454.Pq outlyer
455The peer is discarded by the clustering algorithm as an
456outlyer.
457.It \&+
| 415Displays association data concerning in-spec peers from the
416internally cached list of associations.
417This command performs
418identically to the
419.Ic associations
420except that it displays
421the internally stored data rather than making a new query.
422.It Ic peers
423Obtains a current list peers of the server, along with a
424summary of each peer's state.
425Summary information includes the
426address of the remote peer, the reference ID (0.0.0.0 if this is
427unknown), the stratum of the remote peer, the type of the peer
428(local, unicast, multicast or broadcast), when the last packet was
429received, the polling interval, in seconds, the reachability
430register, in octal, and the current estimated delay, offset and
431dispersion of the peer, all in milliseconds.
432The character in the left margin indicates the fate of this
433peer in the clock selection process.
434Following is a list of these
435characters, the pigeon used in the
436.Ic rv
437command, and a short
438explanation of the condition revealed.
439.Bl -tag -width indent
440.It space
441.Pq reject
442The peer is discarded as unreachable, synchronized to this
443server (synch loop) or outrageous synchronization distance.
444.It x
445.Pq falsetick
446The peer is discarded by the intersection algorithm as a
447falseticker.
448.It \&.
449.Pq excess
450The peer is discarded as not among the first ten peers sorted
451by synchronization distance and so is probably a poor candidate for
452further consideration.
453.It \&-
454.Pq outlyer
455The peer is discarded by the clustering algorithm as an
456outlyer.
457.It \&+
|
458.Pq candidat
| 458.Pq candidate
|
459The peer is a survivor and a candidate for the combining
460algorithm.
461.It \&#
462.Pq selected
463The peer is a survivor, but not among the first six peers
464sorted by synchronization distance.
| 459The peer is a survivor and a candidate for the combining
460algorithm.
461.It \&#
462.Pq selected
463The peer is a survivor, but not among the first six peers
464sorted by synchronization distance.
|
465If the assocation is ephemeral,
| 465If the association is ephemeral,
|
466it may be demobilized to conserve resources.
467.It \&*
468.Pq peer
469The peer has been declared the system peer and lends its
470variables to the system variables.
471.It o
472.Pq (pps.peer)
473The peer has been declared the system peer and lends its
| 466it may be demobilized to conserve resources.
467.It \&*
468.Pq peer
469The peer has been declared the system peer and lends its
470variables to the system variables.
471.It o
472.Pq (pps.peer)
473The peer has been declared the system peer and lends its
|
474variables to thesystem variables.
| 474variables to the system variables.
|
475However, the actual system
476synchronization is derived from a pulse-per-second (PPS) signal,
477either indirectly via the PPS reference clock driver or directly
478via kernel interface.
479.El
480.El
481.Pp
482The
483.Va flash
484variable is a valuable debugging aid.
485It
486displays the results of the original sanity checks defined in the
487NTP specification RFC-1305 and additional ones added in NTP Version
4884.
489There are eleven tests called
490.Sy TEST1
491through
492.Sy TEST11 .
493The tests are performed in a certain order
494designed to gain maximum diagnostic information while protecting
495against accidental or malicious errors.
496The
497.Va flash
498variable
499is first initialized to zero.
500If after each set of tests one or
501more bits are set, the packet is discarded.
502.Pp
503Tests
504.Sy TEST4
505and
506.Sy TEST5
507check the access
508permissions and cryptographic message digest.
509If any bits are set
510after that, the packet is discarded.
511Tests
512.Sy TEST10
513and
514.Sy TEST11
515check the authentication state using Autokey
516public-key cryptography, as described in the
517.Sx Authentication Options
518section of
519.Xr ntp.conf 5 .
520If any bits are set
521and the association has previously been marked reachable, the
522packet is discarded; otherwise, the originate and receive
523timestamps are saved, as required by the NTP protocol, and
524processing continues.
525.Pp
526Tests
527.Sy TEST1
528through
529.Sy TEST3
530check the packet
531timestamps from which the offset and delay are calculated.
532If any
533bits are set, the packet is discarded; otherwise, the packet header
534variables are saved.
535Tests
536.Sy TEST6
537through
538.Sy TEST8
539check the health of the server.
540If any bits are set, the packet is
541discarded; otherwise, the offset and delay relative to the server
542are calculated and saved.
543Test
544.Sy TEST9
545checks the health of
546the association itself.
547If any bits are set, the packet is
548discarded; otherwise, the saved variables are passed to the clock
549filter and mitigation algorithms.
550.Pp
551The
552.Va flash
553bits for each test read in increasing order
554from the least significant bit are defined as follows.
555.Bl -tag -width indent
556.It Sy TEST1
557Duplicate packet.
558The packet is at best a casual retransmission
559and at worst a malicious replay.
560.It Sy TEST2
561Bogus packet.
562The packet is not a reply to a message previously
563sent.
564This can happen when the NTP daemon is restarted and before
565somebody else notices.
566.It Sy TEST3
567Unsynchronized.
568One or more timestamp fields are invalid.
569This
570normally happens when the first packet from a peer is
571received.
572.It Sy TEST4
573Access is denied.
574See the
575.Qq "Access Control"
576page.
577.It Sy TEST5
578Cryptographic authentication fails.
579See the
580.Sx Authentication Options
581section of
582.Xr ntp.conf 5 .
583.It Sy TEST6
584The server is unsynchronized.
585Wind up its clock first.
586.It Sy TEST7
587The server stratum is at the maximum than 15.
588It is probably
589unsynchronized and its clock needs to be wound up.
590.It Sy TEST8
591Either the root delay or dispersion is greater than one second,
592which is highly unlikely unless the peer is synchronized to
593Mars.
594.It Sy TEST9
595Either the peer delay or dispersion is greater than one second,
596which is higly unlikely unless the peer is on Mars.
597.It Sy TEST10
598The autokey protocol has detected an authentication failure.
599See the
600.Sx Authentication Options
601section of
602.Xr ntp.conf 5 .
603.It Sy TEST11
604The autokey protocol has not verified the server or peer is
605authentic and has valid public key credentials.
606See the
607.Sx Authentication Options
608section of
609.Xr ntp.conf 5 .
610.El
611.Pp
612Additional system variables used by the NTP Version 4 Autokey
613support include the following:
614.Bl -tag -width indent
615.It Ic certificate Ar filestamp
616Shows the NTP seconds when the certificate file was
617created.
618.It Ic hostname Ar host
619Shows the name of the host as returned by the Unix
620.Xr gethostname 3
621library function.
622.It Ic flags Ar hex
623Shows the current flag bits, where the
624.Ar hex
625bits
626are interpreted as follows:
627.Bl -tag -width indent
628.It 0x01
629autokey enabled
630.It 0x02
631RSA public/private key files present
632.It 0x04
633PKI certificate file present
634.It 0x08
635Diffie-Hellman parameters file present
636.It 0x10
637NIST leapseconds table file present
638.El
639.It Ic leapseconds Ar filestamp
640Shows the NTP seconds when the NIST leapseconds table file was
641created.
642.It Ic params Ar filestamp
643Shows the NTP seconds when the Diffie-Hellman agreement
644parameter file was created.
645.It Ic publickey Ar filestamp
646Shows the NTP seconds when the RSA public/private key files
647were created.
648.It Ic refresh Ar filestamp
649Shows the NTP seconds when the public cryptographic values were
650refreshed and signed.
651.It Ic tai Ar offset
652Shows the TAI-UTC offset in seconds obtained from the NIST
653leapseconds table.
654.El
655.Pp
656Additional peer variables used by the NTP Version 4 Autokey
657support include the following:
658.Bl -tag -width indent
659.It Ic certificate Ar filestamp
660Shows the NTP seconds when the certificate file was
661created.
662.It Ic flags Ar hex
663Shows the current flag bits, where the
664.Ar hex
665bits are
666interpreted as in the system variable of the same name.
667The bits
668are set in the first autokey message received from the server and
669then reset as the associated data are obtained from the server and
670stored.
671.It Ic hcookie Ar hex
672Shows the host cookie used in the key agreement algorithm.
673.It Ic initkey Ar key
674Shows the initial key used by the key list generator in the
675autokey protocol.
676.It Ic initsequence Ar index
677Shows the initial index used by the key list generator in the
678autokey protocol.
679.It Ic pcookie Ar hex
680Specifies the peer cookie used in the key agreement
681algorithm.
682.It Ic timestamp Ar time
683Shows the NTP seconds when the last autokey key list was
684generated and signed.
685.It Ic pstatus Ar assocID
686Sends a read status request to the server for the given
687association.
688The names and values of the peer variables returned
689will be printed.
690Note that the status word from the header is
| 475However, the actual system
476synchronization is derived from a pulse-per-second (PPS) signal,
477either indirectly via the PPS reference clock driver or directly
478via kernel interface.
479.El
480.El
481.Pp
482The
483.Va flash
484variable is a valuable debugging aid.
485It
486displays the results of the original sanity checks defined in the
487NTP specification RFC-1305 and additional ones added in NTP Version
4884.
489There are eleven tests called
490.Sy TEST1
491through
492.Sy TEST11 .
493The tests are performed in a certain order
494designed to gain maximum diagnostic information while protecting
495against accidental or malicious errors.
496The
497.Va flash
498variable
499is first initialized to zero.
500If after each set of tests one or
501more bits are set, the packet is discarded.
502.Pp
503Tests
504.Sy TEST4
505and
506.Sy TEST5
507check the access
508permissions and cryptographic message digest.
509If any bits are set
510after that, the packet is discarded.
511Tests
512.Sy TEST10
513and
514.Sy TEST11
515check the authentication state using Autokey
516public-key cryptography, as described in the
517.Sx Authentication Options
518section of
519.Xr ntp.conf 5 .
520If any bits are set
521and the association has previously been marked reachable, the
522packet is discarded; otherwise, the originate and receive
523timestamps are saved, as required by the NTP protocol, and
524processing continues.
525.Pp
526Tests
527.Sy TEST1
528through
529.Sy TEST3
530check the packet
531timestamps from which the offset and delay are calculated.
532If any
533bits are set, the packet is discarded; otherwise, the packet header
534variables are saved.
535Tests
536.Sy TEST6
537through
538.Sy TEST8
539check the health of the server.
540If any bits are set, the packet is
541discarded; otherwise, the offset and delay relative to the server
542are calculated and saved.
543Test
544.Sy TEST9
545checks the health of
546the association itself.
547If any bits are set, the packet is
548discarded; otherwise, the saved variables are passed to the clock
549filter and mitigation algorithms.
550.Pp
551The
552.Va flash
553bits for each test read in increasing order
554from the least significant bit are defined as follows.
555.Bl -tag -width indent
556.It Sy TEST1
557Duplicate packet.
558The packet is at best a casual retransmission
559and at worst a malicious replay.
560.It Sy TEST2
561Bogus packet.
562The packet is not a reply to a message previously
563sent.
564This can happen when the NTP daemon is restarted and before
565somebody else notices.
566.It Sy TEST3
567Unsynchronized.
568One or more timestamp fields are invalid.
569This
570normally happens when the first packet from a peer is
571received.
572.It Sy TEST4
573Access is denied.
574See the
575.Qq "Access Control"
576page.
577.It Sy TEST5
578Cryptographic authentication fails.
579See the
580.Sx Authentication Options
581section of
582.Xr ntp.conf 5 .
583.It Sy TEST6
584The server is unsynchronized.
585Wind up its clock first.
586.It Sy TEST7
587The server stratum is at the maximum than 15.
588It is probably
589unsynchronized and its clock needs to be wound up.
590.It Sy TEST8
591Either the root delay or dispersion is greater than one second,
592which is highly unlikely unless the peer is synchronized to
593Mars.
594.It Sy TEST9
595Either the peer delay or dispersion is greater than one second,
596which is higly unlikely unless the peer is on Mars.
597.It Sy TEST10
598The autokey protocol has detected an authentication failure.
599See the
600.Sx Authentication Options
601section of
602.Xr ntp.conf 5 .
603.It Sy TEST11
604The autokey protocol has not verified the server or peer is
605authentic and has valid public key credentials.
606See the
607.Sx Authentication Options
608section of
609.Xr ntp.conf 5 .
610.El
611.Pp
612Additional system variables used by the NTP Version 4 Autokey
613support include the following:
614.Bl -tag -width indent
615.It Ic certificate Ar filestamp
616Shows the NTP seconds when the certificate file was
617created.
618.It Ic hostname Ar host
619Shows the name of the host as returned by the Unix
620.Xr gethostname 3
621library function.
622.It Ic flags Ar hex
623Shows the current flag bits, where the
624.Ar hex
625bits
626are interpreted as follows:
627.Bl -tag -width indent
628.It 0x01
629autokey enabled
630.It 0x02
631RSA public/private key files present
632.It 0x04
633PKI certificate file present
634.It 0x08
635Diffie-Hellman parameters file present
636.It 0x10
637NIST leapseconds table file present
638.El
639.It Ic leapseconds Ar filestamp
640Shows the NTP seconds when the NIST leapseconds table file was
641created.
642.It Ic params Ar filestamp
643Shows the NTP seconds when the Diffie-Hellman agreement
644parameter file was created.
645.It Ic publickey Ar filestamp
646Shows the NTP seconds when the RSA public/private key files
647were created.
648.It Ic refresh Ar filestamp
649Shows the NTP seconds when the public cryptographic values were
650refreshed and signed.
651.It Ic tai Ar offset
652Shows the TAI-UTC offset in seconds obtained from the NIST
653leapseconds table.
654.El
655.Pp
656Additional peer variables used by the NTP Version 4 Autokey
657support include the following:
658.Bl -tag -width indent
659.It Ic certificate Ar filestamp
660Shows the NTP seconds when the certificate file was
661created.
662.It Ic flags Ar hex
663Shows the current flag bits, where the
664.Ar hex
665bits are
666interpreted as in the system variable of the same name.
667The bits
668are set in the first autokey message received from the server and
669then reset as the associated data are obtained from the server and
670stored.
671.It Ic hcookie Ar hex
672Shows the host cookie used in the key agreement algorithm.
673.It Ic initkey Ar key
674Shows the initial key used by the key list generator in the
675autokey protocol.
676.It Ic initsequence Ar index
677Shows the initial index used by the key list generator in the
678autokey protocol.
679.It Ic pcookie Ar hex
680Specifies the peer cookie used in the key agreement
681algorithm.
682.It Ic timestamp Ar time
683Shows the NTP seconds when the last autokey key list was
684generated and signed.
685.It Ic pstatus Ar assocID
686Sends a read status request to the server for the given
687association.
688The names and values of the peer variables returned
689will be printed.
690Note that the status word from the header is
|
691displayed preceding the variables, both in hexidecimal and in
| 691displayed preceding the variables, both in hexadecimal and in
|
692pidgeon English.
693.It Ic readlist Ar assocID
694.It Ic rl Ar assocID
695Requests that the values of the variables in the internal
696variable list be returned by the server.
697If the association ID is
698omitted or is 0 the variables are assumed to be system variables.
699Otherwise they are treated as peer variables.
700If the internal
701variable list is empty a request is sent without data, which should
702induce the remote server to return a default display.
703.It Xo Ic readvar Ar assocID
704.Ar variable_name Ns Op = Ns Ar value
705.Ar ...
706.Xc
707.It Xo Ic rv Ar assocID
708.Ar variable_name Ns Op = Ns Ar value
709.Ar ...
710.Xc
711Requests that the values of the specified variables be returned
712by the server by sending a read variables request.
713If the
714association ID is omitted or is given as zero the variables are
715system variables, otherwise they are peer variables and the values
716returned will be those of the corresponding peer.
717Omitting the
718variable list will send a request with no data which should induce
719the server to return a default display.
720.It Xo Ic writevar Ar assocID
721.Ar variable_name Ns Op = Ns Ar value
722.Ar ...
723.Xc
724Like the readvar request, except the specified variables are
725written instead of read.
726.It Ic writelist Op Ar assocID
727Like the readlist request, except the internal list variables
728are written instead of read.
729.El
730.Sh SEE ALSO
731.Xr ntp.conf 5 ,
732.Xr ntpd 8 ,
733.Xr ntpdc 8
734.Sh BUGS
735The
736.Ic peers
737command is non-atomic and may occasionally result in
738spurious error messages about invalid associations occurring and
739terminating the command.
740The timeout time is a fixed constant,
741which means you wait a long time for timeouts since it assumes sort
742of a worst case.
743The program should improve the timeout estimate as
744it sends queries to a particular host, but doesn't.
| 692pidgeon English.
693.It Ic readlist Ar assocID
694.It Ic rl Ar assocID
695Requests that the values of the variables in the internal
696variable list be returned by the server.
697If the association ID is
698omitted or is 0 the variables are assumed to be system variables.
699Otherwise they are treated as peer variables.
700If the internal
701variable list is empty a request is sent without data, which should
702induce the remote server to return a default display.
703.It Xo Ic readvar Ar assocID
704.Ar variable_name Ns Op = Ns Ar value
705.Ar ...
706.Xc
707.It Xo Ic rv Ar assocID
708.Ar variable_name Ns Op = Ns Ar value
709.Ar ...
710.Xc
711Requests that the values of the specified variables be returned
712by the server by sending a read variables request.
713If the
714association ID is omitted or is given as zero the variables are
715system variables, otherwise they are peer variables and the values
716returned will be those of the corresponding peer.
717Omitting the
718variable list will send a request with no data which should induce
719the server to return a default display.
720.It Xo Ic writevar Ar assocID
721.Ar variable_name Ns Op = Ns Ar value
722.Ar ...
723.Xc
724Like the readvar request, except the specified variables are
725written instead of read.
726.It Ic writelist Op Ar assocID
727Like the readlist request, except the internal list variables
728are written instead of read.
729.El
730.Sh SEE ALSO
731.Xr ntp.conf 5 ,
732.Xr ntpd 8 ,
733.Xr ntpdc 8
734.Sh BUGS
735The
736.Ic peers
737command is non-atomic and may occasionally result in
738spurious error messages about invalid associations occurring and
739terminating the command.
740The timeout time is a fixed constant,
741which means you wait a long time for timeouts since it assumes sort
742of a worst case.
743The program should improve the timeout estimate as
744it sends queries to a particular host, but doesn't.
|