1.\"
|
2.\" $FreeBSD: head/usr.sbin/ntp/doc/ntpdc.8 82501 2001-08-29 14:50:56Z sheldonh $
|
| 2.\" $FreeBSD: head/usr.sbin/ntp/doc/ntpdc.8 89625 2002-01-21 20:12:02Z roberto $ |
3.\"
4.Dd January 7, 2000
5.Dt NTPDC 8
6.Os
7.Sh NAME
8.Nm ntpdc
9.Nd special NTP query program
10.Sh SYNOPSIS
11.Nm
12.Op Fl ilnps
13.Op Fl c Ar command
14.Op Ar host ...
15.Sh DESCRIPTION
16.Nm
17is used to query the
18.Xr ntpd 8
19daemon about its
20current state and to request changes in that state.
21The program may
22be run either in interactive mode or controlled using command line
23arguments.
24Extensive state and statistics information is available
25through the
26.Nm
27interface.
28In addition, nearly all the
29configuration options which can be specified at startup using
30ntpd's configuration file may also be specified at run time using
31.Nm .
32.Pp
33The following options are available:
34.Bl -tag -width indent
35.It Fl c Ar command
36The following argument is interpreted as an interactive format
37command and is added to the list of commands to be executed on the
38specified host(s).
39Multiple
40.Fl c
41options may be given.
42.It Fl i
43Force
44.Nm
45to operate in interactive mode.
46Prompts
47will be written to the standard output and commands read from the
48standard input.
49.It Fl l
50Obtain a list of peers which are known to the server(s).
51This
52switch is equivalent to
53.Ql -c listpeers .
54.It Fl n
55Output all host addresses in dotted-quad numeric format rather
56than converting to the canonical host names.
57.It Fl p
58Print a list of the peers known to the server as well as a
59summary of their state.
60This is equivalent to
61.Ql -c peers .
62.It Fl s
63Print a list of the peers known to the server as well as a
64summary of their state, but in a slightly different format than the
65.Fl p
66switch.
67This is equivalent to
68.Ql -c dmpeers .
69.El
70.Pp
71If one or more request options are included on the command line
72when
73.Nm
74is executed, each of the requests will be sent
75to the NTP servers running on each of the hosts given as command
76line arguments, or on localhost by default.
77If no request options
78are given,
79.Nm
80will attempt to read commands from the
81standard input and execute these on the NTP server running on the
82first host given on the command line, again defaulting to localhost
83when no other host is specified.
84.Nm
85will prompt for
86commands if the standard input is a terminal device.
87.Pp
88.Nm
89uses NTP mode 7 packets to communicate with the
90NTP server, and hence can be used to query any compatable server on
91the network which permits it.
92Note that since NTP is a UDP protocol
93this communication will be somewhat unreliable, especially over
94large distances in terms of network topology.
95.Nm
96makes
97no attempt to retransmit requests, and will time requests out if
98the remote host is not heard from within a suitable timeout
99time.
100.Pp
101The operation of
102.Nm
103are specific to the particular
104implementation of the
105.Xr ntpd 8
106daemon and can be expected to
107work only with this and maybe some previous versions of the daemon.
108Requests from a remote
109.Nm
110program which affect the
111state of the local server must be authenticated, which requires
112both the remote program and local server share a common key and key
113identifier.
114Specifying a command line option other than
115.Fl i
116or
117.Fl n
118will cause the specified query (queries) to be sent to
119the indicated host(s) immediately.
120Otherwise,
121.Nm
122will
123attempt to read interactive format commands from the standard
124input.
125.Ss "Interactive Commands"
126Interactive format commands consist of a keyword followed by zero
127to four arguments.
128Only enough characters of the full keyword to
129uniquely identify the command need be typed.
130The output of a
131command is normally sent to the standard output, but optionally the
132output of individual commands may be sent to a file by appending a
|
133.Ql \&; ,
|
| 133.Ql \&> , |
134followed by a file name, to the command line.
135.Pp
136A number of interactive format commands are executed entirely
137within the
138.Nm
139program itself and do not result in NTP
140mode 7 requests being sent to a server.
141These are described
142following.
143.Bl -tag -width indent
144.It Ic \&? Ar command_keyword
145.It Ic help Ar command_keyword
146A
147.Ic \&?
148will print a list of all the command
149keywords known to this incarnation of
150.Nm .
151A
152.Ic \&?
153followed by a command keyword will print function and usage
154information about the command.
155This command is probably a better
156source of information about
157.Xr ntpq 8
158than this manual
159page.
160.It Ic delay Ar milliseconds
161Specify a time interval to be added to timestamps included in
162requests which require authentication.
163This is used to enable
164(unreliable) server reconfiguration over long delay network paths
165or between machines whose clocks are unsynchronized.
166Actually the
167server does not now require timestamps in authenticated requests,
168so this command may be obsolete.
169.It Ic host Ar hostname
170Set the host to which future queries will be sent.
171Hostname may
172be either a host name or a numeric address.
173.It Ic hostnames Op Cm yes | Cm no
174If
175.Cm yes
176is specified, host names are printed in
177information displays.
178If
179.Cm no
180is specified, numeric
181addresses are printed instead.
182The default is
183.Cm yes ,
184unless
185modified using the command line
186.Fl n
187switch.
188.It Ic keyid Ar keyid
189This command allows the specification of a key number to be
190used to authenticate configuration requests.
191This must correspond
192to a key number the server has been configured to use for this
193purpose.
194.It Ic quit
195Exit
196.Nm .
197.It Ic passwd
198This command prompts you to type in a password (which will not
199be echoed) which will be used to authenticate configuration
200requests.
201The password must correspond to the key configured for
202use by the NTP server for this purpose if such requests are to be
203successful.
204.It Ic timeout Ar milliseconds
205Specify a timeout period for responses to server queries.
206The
207default is about 8000 milliseconds.
208Note that since
209.Nm
210retries each query once after a timeout, the total waiting time for
211a timeout will be twice the timeout value set.
212.El
213.Ss "Control Message Commands"
214Query commands result in NTP mode 7 packets containing requests for
215information being sent to the server.
216These are read-only commands
217in that they make no modification of the server configuration
218state.
219.Bl -tag -width indent
220.It Ic listpeers
221Obtains and prints a brief list of the peers for which the
222server is maintaining state.
223These should include all configured
224peer associations as well as those peers whose stratum is such that
225they are considered by the server to be possible future
226synchonization candidates.
227.It Ic peers
228Obtains a list of peers for which the server is maintaining
229state, along with a summary of that state.
230Summary information
231includes the address of the remote peer, the local interface
232address (0.0.0.0 if a local address has yet to be determined), the
233stratum of the remote peer (a stratum of 16 indicates the remote
234peer is unsynchronized), the polling interval, in seconds, the
235reachability register, in octal, and the current estimated delay,
236offset and dispersion of the peer, all in seconds.
237.Pp
238The character in the left margin indicates the mode this peer
239entry is operating in.
240A
241.Ql \&+
242denotes symmetric active, a
243.Ql \&-
244indicates symmetric passive, a
245.Ql \&=
246means the
247remote server is being polled in client mode, a
248.Ql \&^
249indicates that the server is broadcasting to this address, a
250.Ql \&~
251denotes that the remote peer is sending broadcasts and a
252.Ql \&*
253marks the peer the server is currently synchonizing
254to.
255.Pp
256The contents of the host field may be one of four forms.
257It may
258be a host name, an IP address, a reference clock implementation
259name with its parameter or
260.Fn REFCLK "implementation_number" "parameter" .
261On
262.Ic hostnames
263.Cm no
264only IP-addresses
265will be displayed.
266.It Ic dmpeers
267A slightly different peer summary list.
268Identical to the output
269of the
270.Ic peers
271command, except for the character in the
272leftmost column.
273Characters only appear beside peers which were
274included in the final stage of the clock selection algorithm.
275A
276.Ql \&.
277indicates that this peer was cast off in the falseticker
278detection, while a
279.Ql \&+
280indicates that the peer made it
281through.
282A
283.Ql \&*
284denotes the peer the server is currently
285synchronizing with.
286.It Ic showpeer Ar peer_address ...
287Shows a detailed display of the current peer variables for one
288or more peers.
289Most of these values are described in the NTP
290Version 2 specification.
291.It Ic pstats Ar peer_address ...
292Show per-peer statistic counters associated with the specified
293peer(s).
294.It Ic clockinfo Ar clock_peer_address ...
295Obtain and print information concerning a peer clock.
296The
297values obtained provide information on the setting of fudge factors
298and other clock performance information.
299.It Ic kerninfo
300Obtain and print kernel phase-lock loop operating parameters.
301This information is available only if the kernel has been specially
302modified for a precision timekeeping function.
303.It Ic loopinfo Op Cm oneline | Cm multiline
304Print the values of selected loop filter variables.
305The loop
306filter is the part of NTP which deals with adjusting the local
307system clock.
308The
309.Sq offset
310is the last offset given to the
311loop filter by the packet processing code.
312The
313.Sq frequency
314is the frequency error of the local clock in parts-per-million
315(ppm).
316The
317.Sq time_const
318controls the stiffness of the
319phase-lock loop and thus the speed at which it can adapt to
320oscillator drift.
321The
322.Sq watchdog timer
323value is the number
324of seconds which have elapsed since the last sample offset was
325given to the loop filter.
326The
327.Cm oneline
328and
329.Cm multiline
330options specify the format in which this
331information is to be printed, with
332.Cm multiline
333as the
334default.
335.It Ic sysinfo
336Print a variety of system state variables, i.e., state related
337to the local server.
338All except the last four lines are described
339in the NTP Version 3 specification, RFC-1305.
340.Pp
341The
342.Sq system flags
343show various system flags, some of
344which can be set and cleared by the
345.Ic enable
346and
347.Ic disable
348configuration commands, respectively.
349These are
350the
351.Cm auth ,
352.Cm bclient ,
353.Cm monitor ,
354.Cm pll ,
355.Cm pps
356and
357.Cm stats
358flags.
359See the
360.Xr ntpd 8
361documentation for the meaning of these flags.
362There
363are two additional flags which are read only, the
364.Cm kernel_pll
365and
366.Cm kernel_pps .
367These flags indicate
368the synchronization status when the precision time kernel
369modifications are in use.
370The
371.Sq kernel_pll
372indicates that
373the local clock is being disciplined by the kernel, while the
374.Sq kernel_pps
375indicates the kernel discipline is provided by the PPS
376signal.
377.Pp
378The
379.Sq stability
380is the residual frequency error remaining
|
381afterthe system frequency correction is applied and is intended for
|
| 381after the system frequency correction is applied and is intended for |
382maintenance and debugging.
383In most architectures, this value will
384initially decrease from as high as 500 ppm to a nominal value in
385the range .01 to 0.1 ppm.
386If it remains high for some time after
387starting the daemon, something may be wrong with the local clock,
388or the value of the kernel variable
389.Va kern.clockrate.tick
390may be
391incorrect.
392.Pp
393The
|
394.Ic broadcastdelay
|
| 394.Sq broadcastdelay |
395shows the default broadcast delay,
396as set by the
397.Ic broadcastdelay
398configuration command.
399.Pp
400The
401.Sq authdelay
402shows the default authentication delay,
403as set by the
404.Ic authdelay
405configuration command.
406.It Ic sysstats
407Print statistics counters maintained in the protocol
408module.
409.It Ic memstats
410Print statistics counters related to memory allocation
411code.
412.It Ic iostats
413Print statistics counters maintained in the input-output
414module.
415.It Ic timerstats
416Print statistics counters maintained in the timer/event queue
417support code.
418.It Ic reslist
419Obtain and print the server's restriction list.
420This list is
421(usually) printed in sorted order and may help to understand how
422the restrictions are applied.
423.It Ic monlist Op Ar version
424Obtain and print traffic counts collected and maintained by the
425monitor facility.
426The version number should not normally need to be
427specified.
|
428.It Ic clkbug clock_peer_address ...
|
| 428.It Ic clkbug Ar clock_peer_address ... |
429Obtain debugging information for a reference clock driver.
430This
431information is provided only by some clock drivers and is mostly
432undecodable without a copy of the driver source in hand.
433.El
434.Ss "Runtime Configuration Requests"
435All requests which cause state changes in the server are
436authenticated by the server using a configured NTP key (the
437facility can also be disabled by the server by not configuring a
438key).
439The key number and the corresponding key must also be made
440known to
441.Nm .
442This can be done using the
443.Ic keyid
444and
445.Ic passwd
446commands, the latter of which will prompt at the terminal for a
447password to use as the encryption key.
448You will also be prompted
449automatically for both the key number and password the first time a
450command which would result in an authenticated request to the
451server is given.
452Authentication not only provides verification that
453the requester has permission to make such changes, but also gives
454an extra degree of protection again transmission errors.
455.Pp
456Authenticated requests always include a timestamp in the packet
457data, which is included in the computation of the authentication
458code.
459This timestamp is compared by the server to its receive time
460stamp.
461If they differ by more than a small amount the request is
462rejected.
463This is done for two reasons.
464First, it makes simple
465replay attacks on the server, by someone who might be able to
466overhear traffic on your LAN, much more difficult.
467Second, it makes
468it more difficult to request configuration changes to your server
469from topologically remote hosts.
470While the reconfiguration facility
471will work well with a server on the local host, and may work
472adequately between time-synchronized hosts on the same LAN, it will
473work very poorly for more distant hosts.
474As such, if reasonable
475passwords are chosen, care is taken in the distribution and
476protection of keys and appropriate source address restrictions are
477applied, the run time reconfiguration facility should provide an
478adequate level of security.
479.Pp
480The following commands all make authenticated requests.
481.Bl -tag -width indent
482.It Xo Ic addpeer Ar peer_address
483.Op Ar keyid
484.Op Ar version
485.Op Cm prefer
486.Xc
487Add a configured peer association at the given address and
488operating in symmetric active mode.
489Note that an existing
490association with the same peer may be deleted when this command is
491executed, or may simply be converted to conform to the new
492configuration, as appropriate.
493If the optional
494.Ar keyid
495is a
496nonzero integer, all outgoing packets to the remote server will
497have an authentication field attached encrypted with this key.
498If
499the value is 0 (or not given) no authentication will be done.
500The
501.Ar version
502can be 1, 2 or 3 and defaults to 3.
503The
504.Cm prefer
505keyword indicates a preferred peer (and thus will
506be used primarily for clock synchronisation if possible).
507The
508preferred peer also determines the validity of the PPS signal - if
509the preferred peer is suitable for synchronisation so is the PPS
510signal.
511.It Xo Ic addserver Ar peer_address
512.Op Ar keyid
513.Op Ar version
514.Op Cm prefer
515.Xc
516Identical to the addpeer command, except that the operating
517mode is client.
518.It Xo Ic broadcast Ar peer_address
519.Op Ar keyid
520.Op Ar version
521.Op Cm prefer
522.Xc
523Identical to the addpeer command, except that the operating
524mode is broadcast.
525In this case a valid key identifier and key are
526required.
527The
528.Ar peer_address
529parameter can be the broadcast
530address of the local network or a multicast group address assigned
531to NTP.
532If a multicast address, a multicast-capable kernel is
533required.
534.It Ic unconfig Ar peer_address ...
535This command causes the configured bit to be removed from the
536specified peer(s).
537In many cases this will cause the peer
538association to be deleted.
539When appropriate, however, the
540association may persist in an unconfigured mode if the remote peer
541is willing to continue on in this fashion.
542.It Xo Ic fudge Ar peer_address
543.Op Cm time1
544.Op Cm time2
545.Op Ar stratum
546.Op Ar refid
547.Xc
548This command provides a way to set certain data for a reference
549clock.
550See the source listing for further information.
|
551.It enable Ar flag ...
552.It disable Ar flag ...
|
551.It Ic enable Ar flag ...
552.It Ic disable Ar flag ... |
553These commands operate in the same way as the
554.Ic enable
555and
556.Ic disable
557configuration file commands of
558.Xr ntpd 8 .
559Following is a description of the flags.
560Note that only the
561.Cm auth ,
562.Cm bclient ,
563.Cm monitor ,
564.Cm pll ,
565.Cm pps
566and
567.Cm stats
568flags can be set by
569.Nm ;
570the
571.Cm pll_kernel
572and
573.Cm pps_kernel
574flags are
575read-only.
576.Bl -tag -width indent
577.It Cm auth
578Enables the server to synchronize with unconfigured peers only
579if the peer has been correctly authenticated using a trusted key
580and key identifier.
581The default for this flag is enable.
582.It Cm bclient
583Enables the server to listen for a message from a broadcast or
584multicast server, as in the
585.Ic multicastclient
586command with
587default address.
588The default for this flag is disable.
589.It Cm monitor
590Enables the monitoring facility.
591See the
592.Ic monlist
593command for further information.
594The
595default for this flag is enable.
596.It Cm pll
597Enables the server to adjust its local clock by means of NTP.
598If disabled, the local clock free-runs at its intrinsic time and
599frequency offset.
600This flag is useful in case the local clock is
601controlled by some other device or protocol and NTP is used only to
602provide synchronization to other clients.
603In this case, the local
604clock driver is used.
605See the
606.Qq "Reference Clock Drivers"
607page
608(available as part of the HTML documentation
609provided in
610.Pa /usr/share/doc/ntp )
611page for further information.
612The default for
613this flag is enable.
614.It Cm pps
615Enables the pulse-per-second (PPS) signal when frequency and
616time is disciplined by the precision time kernel modifications.
617See
618the
619.Qq "A Kernel Model for Precision Timekeeping"
620page for further information.
621The default for this flag is
622disable.
623.It Cm stats
624Enables the statistics facility.
625See the
626.Sx Monitoring Options
627section
628of the
629.Xr ntp.conf 5
630page for further information.
631The default for this flag is enable.
632.It Cm pll_kernel
633When the precision time kernel modifications are installed,
634this indicates the kernel controls the clock discipline; otherwise,
635the daemon controls the clock discipline.
636.It Cm pps_kernel
637When the precision time kernel modifications are installed and
638a pulse-per-second (PPS) signal is available, this indicates the
639PPS signal controls the clock discipline; otherwise, the daemon or
640kernel controls the clock discipline, as indicated by the
641.Cm pll_kernel
642flag.
643.El
644.It Xo Ic restrict Ar address Ar mask
645.Ar flag ...
646.Xc
647This command operates in the same way as the
648.Ic restrict
649configuration file commands of
650.Xr ntpd 8 .
651.It Xo Ic unrestrict Ar address Ar mask
652.Ar flag ...
653.Xc
654Unrestrict the matching entry from the restrict list.
655.It Xo Ic delrestrict Ar address Ar mask
656.Op Cm ntpport
657.Xc
658Delete the matching entry from the restrict list.
659.It Ic readkeys
660Causes the current set of authentication keys to be purged and
661a new set to be obtained by rereading the keys file (which must
662have been specified in the
663.Xr ntpd 8
664configuration file).
665This
666allows encryption keys to be changed without restarting the
667server.
668.It Ic trustedkey Ar keyid ...
669.It Ic untrustedkey Ar keyid ...
670These commands operate in the same way as the
671.Ic trustedkey
672and
673.Ic untrustedkey
674configuration file
675commands of
676.Xr ntpd 8 .
677.It Ic authinfo
678Returns information concerning the authentication module,
679including known keys and counts of encryptions and decryptions
680which have been done.
681.It Ic traps
682Display the traps set in the server.
683See the source listing for
684further information.
685.It Xo Ic addtrap Ar address
686.Op Ar port
687.Op Ar interface
688.Xc
689Set a trap for asynchronous messages.
690See the source listing
691for further information.
692.It Xo Ic clrtrap Ar address
693.Op Ar port
694.Op Ar interface
695.Xc
696Clear a trap for asynchronous messages.
697See the source listing
698for further information.
699.It Ic reset
700Clear the statistics counters in various modules of the server.
701See the source listing for further information.
702.El
703.Sh SEE ALSO
704.Xr ntp.conf 5 ,
705.Xr ntpd 8
706.Rs
707.%A David L. Mills
708.%T Network Time Protocol (Version 3)
709.%O RFC1305
710.Re
711.Sh BUGS
712.Nm
713is a crude hack.
714Much of the information it shows is
715deadly boring and could only be loved by its implementer.
716The
717program was designed so that new (and temporary) features were easy
718to hack in, at great expense to the program's ease of use.
719Despite
720this, the program is occasionally useful.
|