2 .\" $FreeBSD: src/usr.sbin/ntp/doc/ntpdc.8,v 1.2.2.8 2003/03/11 22:31:29 trhodes Exp $
9 .Nd special NTP query program
18 utility is used to query the
21 current state and to request changes in that state.
23 be run either in interactive mode or controlled using command line
25 Extensive state and statistics information is available
29 In addition, nearly all the
30 configuration options which can be specified at startup using
31 ntpd's configuration file may also be specified at run time using
34 The following options are available:
35 .Bl -tag -width indent
37 The following argument is interpreted as an interactive format
38 command and is added to the list of commands to be executed on the
46 to operate in interactive mode.
48 will be written to the standard output and commands read from the
51 Obtain a list of peers which are known to the server(s).
53 switch is equivalent to
56 Output all host addresses in dotted-quad numeric format rather
57 than converting to the canonical host names.
59 Print a list of the peers known to the server as well as a
60 summary of their state.
64 Print a list of the peers known to the server as well as a
65 summary of their state, but in a slightly different format than the
72 If one or more request options are included on the command line
75 is executed, each of the requests will be sent
76 to the NTP servers running on each of the hosts given as command
77 line arguments, or on localhost by default.
81 will attempt to read commands from the
82 standard input and execute these on the NTP server running on the
83 first host given on the command line, again defaulting to localhost
84 when no other host is specified.
87 utility will prompt for
88 commands if the standard input is a terminal device.
92 utility uses NTP mode 7 packets to communicate with the
93 NTP server, and hence can be used to query any compatible server on
94 the network which permits it.
95 Note that since NTP is a UDP protocol
96 this communication will be somewhat unreliable, especially over
97 large distances in terms of network topology.
101 no attempt to retransmit requests, and will time requests out if
102 the remote host is not heard from within a suitable timeout
107 are specific to the particular
108 implementation of the
110 daemon and can be expected to
111 work only with this and maybe some previous versions of the daemon.
112 Requests from a remote
114 utility which affect the
115 state of the local server must be authenticated, which requires
116 both the remote program and local server share a common key and key
118 Specifying a command line option other than
122 will cause the specified query (queries) to be sent to
123 the indicated host(s) immediately.
127 attempt to read interactive format commands from the standard
129 .Ss "Interactive Commands"
130 Interactive format commands consist of a keyword followed by zero
132 Only enough characters of the full keyword to
133 uniquely identify the command need be typed.
135 command is normally sent to the standard output, but optionally the
136 output of individual commands may be sent to a file by appending a
138 followed by a file name, to the command line.
140 A number of interactive format commands are executed entirely
143 utility itself and do not result in NTP
144 mode 7 requests being sent to a server.
147 .Bl -tag -width indent
148 .It Ic \&? Ar command_keyword
149 .It Ic help Ar command_keyword
152 will print a list of all the command
153 keywords known to this incarnation of
157 followed by a command keyword will print function and usage
158 information about the command.
159 This command is probably a better
160 source of information about
164 .It Ic delay Ar milliseconds
165 Specify a time interval to be added to timestamps included in
166 requests which require authentication.
167 This is used to enable
168 (unreliable) server reconfiguration over long delay network paths
169 or between machines whose clocks are unsynchronized.
171 server does not now require timestamps in authenticated requests,
172 so this command may be obsolete.
173 .It Ic host Ar hostname
174 Set the host to which future queries will be sent.
176 be either a host name or a numeric address.
177 .It Ic hostnames Op Cm yes | Cm no
180 is specified, host names are printed in
181 information displays.
184 is specified, numeric
185 addresses are printed instead.
189 modified using the command line
192 .It Ic keyid Ar keyid
193 This command allows the specification of a key number to be
194 used to authenticate configuration requests.
196 to a key number the server has been configured to use for this
202 This command prompts you to type in a password (which will not
203 be echoed) which will be used to authenticate configuration
205 The password must correspond to the key configured for
206 use by the NTP server for this purpose if such requests are to be
208 .It Ic timeout Ar milliseconds
209 Specify a timeout period for responses to server queries.
211 default is about 8000 milliseconds.
214 retries each query once after a timeout, the total waiting time for
215 a timeout will be twice the timeout value set.
217 .Ss "Control Message Commands"
218 Query commands result in NTP mode 7 packets containing requests for
219 information being sent to the server.
220 These are read-only commands
221 in that they make no modification of the server configuration
223 .Bl -tag -width indent
225 Obtains and prints a brief list of the peers for which the
226 server is maintaining state.
227 These should include all configured
228 peer associations as well as those peers whose stratum is such that
229 they are considered by the server to be possible future
230 synchonization candidates.
232 Obtains a list of peers for which the server is maintaining
233 state, along with a summary of that state.
235 includes the address of the remote peer, the local interface
236 address (0.0.0.0 if a local address has yet to be determined), the
237 stratum of the remote peer (a stratum of 16 indicates the remote
238 peer is unsynchronized), the polling interval, in seconds, the
239 reachability register, in octal, and the current estimated delay,
240 offset and dispersion of the peer, all in seconds.
242 The character in the left margin indicates the mode this peer
243 entry is operating in.
246 denotes symmetric active, a
248 indicates symmetric passive, a
251 remote server is being polled in client mode, a
253 indicates that the server is broadcasting to this address, a
255 denotes that the remote peer is sending broadcasts and a
257 marks the peer the server is currently synchronizing
260 The contents of the host field may be one of four forms.
262 be a host name, an IP address, a reference clock implementation
263 name with its parameter or
264 .Fn REFCLK "implementation_number" "parameter" .
271 A slightly different peer summary list.
272 Identical to the output
275 command, except for the character in the
277 Characters only appear beside peers which were
278 included in the final stage of the clock selection algorithm.
281 indicates that this peer was cast off in the falseticker
284 indicates that the peer made it
288 denotes the peer the server is currently
290 .It Ic showpeer Ar peer_address ...
291 Shows a detailed display of the current peer variables for one
293 Most of these values are described in the NTP
294 Version 2 specification.
295 .It Ic pstats Ar peer_address ...
296 Show per-peer statistic counters associated with the specified
298 .It Ic clockinfo Ar clock_peer_address ...
299 Obtain and print information concerning a peer clock.
301 values obtained provide information on the setting of fudge factors
302 and other clock performance information.
304 Obtain and print kernel phase-lock loop operating parameters.
305 This information is available only if the kernel has been specially
306 modified for a precision timekeeping function.
307 .It Ic loopinfo Op Cm oneline | Cm multiline
308 Print the values of selected loop filter variables.
310 filter is the part of NTP which deals with adjusting the local
314 is the last offset given to the
315 loop filter by the packet processing code.
318 is the frequency error of the local clock in parts-per-million
322 controls the stiffness of the
323 phase-lock loop and thus the speed at which it can adapt to
328 of seconds which have elapsed since the last sample offset was
329 given to the loop filter.
334 options specify the format in which this
335 information is to be printed, with
340 Print a variety of system state variables, i.e., state related
342 All except the last four lines are described
343 in the NTP Version 3 specification, RFC-1305.
347 show various system flags, some of
348 which can be set and cleared by the
352 configuration commands, respectively.
365 documentation for the meaning of these flags.
367 are two additional flags which are read only, the
372 the synchronization status when the precision time kernel
373 modifications are in use.
377 the local clock is being disciplined by the kernel, while the
379 indicates the kernel discipline is provided by the PPS
384 is the residual frequency error remaining
385 after the system frequency correction is applied and is intended for
386 maintenance and debugging.
387 In most architectures, this value will
388 initially decrease from as high as 500 ppm to a nominal value in
389 the range .01 to 0.1 ppm.
390 If it remains high for some time after
391 starting the daemon, something may be wrong with the local clock,
392 or the value of the kernel variable
393 .Va kern.clockrate.tick
399 shows the default broadcast delay,
402 configuration command.
406 shows the default authentication delay,
409 configuration command.
411 Print statistics counters maintained in the protocol
414 Print statistics counters related to memory allocation
417 Print statistics counters maintained in the input-output
420 Print statistics counters maintained in the timer/event queue
423 Obtain and print the server's restriction list.
425 (usually) printed in sorted order and may help to understand how
426 the restrictions are applied.
427 .It Ic monlist Op Ar version
428 Obtain and print traffic counts collected and maintained by the
430 The version number should not normally need to be
432 .It Ic clkbug Ar clock_peer_address ...
433 Obtain debugging information for a reference clock driver.
435 information is provided only by some clock drivers and is mostly
436 undecodable without a copy of the driver source in hand.
438 .Ss "Runtime Configuration Requests"
439 All requests which cause state changes in the server are
440 authenticated by the server using a configured NTP key (the
441 facility can also be disabled by the server by not configuring a
443 The key number and the corresponding key must also be made
446 This can be done using the
450 commands, the latter of which will prompt at the terminal for a
451 password to use as the encryption key.
452 You will also be prompted
453 automatically for both the key number and password the first time a
454 command which would result in an authenticated request to the
456 Authentication not only provides verification that
457 the requester has permission to make such changes, but also gives
458 an extra degree of protection again transmission errors.
460 Authenticated requests always include a timestamp in the packet
461 data, which is included in the computation of the authentication
463 This timestamp is compared by the server to its receive time
465 If they differ by more than a small amount the request is
467 This is done for two reasons.
468 First, it makes simple
469 replay attacks on the server, by someone who might be able to
470 overhear traffic on your LAN, much more difficult.
472 it more difficult to request configuration changes to your server
473 from topologically remote hosts.
474 While the reconfiguration facility
475 will work well with a server on the local host, and may work
476 adequately between time-synchronized hosts on the same LAN, it will
477 work very poorly for more distant hosts.
478 As such, if reasonable
479 passwords are chosen, care is taken in the distribution and
480 protection of keys and appropriate source address restrictions are
481 applied, the run time reconfiguration facility should provide an
482 adequate level of security.
484 The following commands all make authenticated requests.
485 .Bl -tag -width indent
486 .It Xo Ic addpeer Ar peer_address
491 Add a configured peer association at the given address and
492 operating in symmetric active mode.
493 Note that an existing
494 association with the same peer may be deleted when this command is
495 executed, or may simply be converted to conform to the new
496 configuration, as appropriate.
500 nonzero integer, all outgoing packets to the remote server will
501 have an authentication field attached encrypted with this key.
503 the value is 0 (or not given) no authentication will be done.
506 can be 1, 2 or 3 and defaults to 3.
509 keyword indicates a preferred peer (and thus will
510 be used primarily for clock synchronisation if possible).
512 preferred peer also determines the validity of the PPS signal - if
513 the preferred peer is suitable for synchronisation so is the PPS
515 .It Xo Ic addserver Ar peer_address
520 Identical to the addpeer command, except that the operating
522 .It Xo Ic broadcast Ar peer_address
527 Identical to the addpeer command, except that the operating
529 In this case a valid key identifier and key are
533 parameter can be the broadcast
534 address of the local network or a multicast group address assigned
536 If a multicast address, a multicast-capable kernel is
538 .It Ic unconfig Ar peer_address ...
539 This command causes the configured bit to be removed from the
541 In many cases this will cause the peer
542 association to be deleted.
543 When appropriate, however, the
544 association may persist in an unconfigured mode if the remote peer
545 is willing to continue on in this fashion.
546 .It Xo Ic fudge Ar peer_address
552 This command provides a way to set certain data for a reference
554 See the source listing for further information.
555 .It Ic enable Ar flag ...
556 .It Ic disable Ar flag ...
557 These commands operate in the same way as the
561 configuration file commands of
563 Following is a description of the flags.
580 .Bl -tag -width indent
582 Enables the server to synchronize with unconfigured peers only
583 if the peer has been correctly authenticated using a trusted key
585 The default for this flag is enable.
587 Enables the server to listen for a message from a broadcast or
588 multicast server, as in the
592 The default for this flag is disable.
594 Enables the monitoring facility.
597 command for further information.
599 default for this flag is enable.
601 Enables the server to adjust its local clock by means of NTP.
602 If disabled, the local clock free-runs at its intrinsic time and
604 This flag is useful in case the local clock is
605 controlled by some other device or protocol and NTP is used only to
606 provide synchronization to other clients.
607 In this case, the local
608 clock driver is used.
610 .Qq "Reference Clock Drivers"
612 (available as part of the HTML documentation
614 .Pa /usr/share/doc/ntp )
615 page for further information.
619 Enables the pulse-per-second (PPS) signal when frequency and
620 time is disciplined by the precision time kernel modifications.
623 .Qq "A Kernel Model for Precision Timekeeping"
624 page for further information.
625 The default for this flag is
628 Enables the statistics facility.
630 .Sx Monitoring Options
634 page for further information.
635 The default for this flag is enable.
637 When the precision time kernel modifications are installed,
638 this indicates the kernel controls the clock discipline; otherwise,
639 the daemon controls the clock discipline.
641 When the precision time kernel modifications are installed and
642 a pulse-per-second (PPS) signal is available, this indicates the
643 PPS signal controls the clock discipline; otherwise, the daemon or
644 kernel controls the clock discipline, as indicated by the
648 .It Xo Ic restrict Ar address Ar mask
651 This command operates in the same way as the
653 configuration file commands of
655 .It Xo Ic unrestrict Ar address Ar mask
658 Unrestrict the matching entry from the restrict list.
659 .It Xo Ic delrestrict Ar address Ar mask
662 Delete the matching entry from the restrict list.
664 Causes the current set of authentication keys to be purged and
665 a new set to be obtained by rereading the keys file (which must
666 have been specified in the
670 allows encryption keys to be changed without restarting the
672 .It Ic trustedkey Ar keyid ...
673 .It Ic untrustedkey Ar keyid ...
674 These commands operate in the same way as the
682 Returns information concerning the authentication module,
683 including known keys and counts of encryptions and decryptions
684 which have been done.
686 Display the traps set in the server.
687 See the source listing for
689 .It Xo Ic addtrap Ar address
693 Set a trap for asynchronous messages.
694 See the source listing
695 for further information.
696 .It Xo Ic clrtrap Ar address
700 Clear a trap for asynchronous messages.
701 See the source listing
702 for further information.
704 Clear the statistics counters in various modules of the server.
705 See the source listing for further information.
712 .%T Network Time Protocol (Version 3)
718 utility is a crude hack.
719 Much of the information it shows is
720 deadly boring and could only be loved by its implementer.
722 program was designed so that new (and temporary) features were easy
723 to hack in, at great expense to the program's ease of use.
725 this, the program is occasionally useful.