2 .\" $FreeBSD: src/usr.sbin/ntp/doc/ntpdc.8,v 1.2.2.8 2003/03/11 22:31:29 trhodes Exp $
3 .\" $DragonFly: src/usr.sbin/ntp/doc/Attic/ntpdc.8,v 1.2 2003/06/17 04:29:58 dillon Exp $
10 .Nd special NTP query program
19 utility is used to query the
22 current state and to request changes in that state.
24 be run either in interactive mode or controlled using command line
26 Extensive state and statistics information is available
30 In addition, nearly all the
31 configuration options which can be specified at startup using
32 ntpd's configuration file may also be specified at run time using
35 The following options are available:
36 .Bl -tag -width indent
38 The following argument is interpreted as an interactive format
39 command and is added to the list of commands to be executed on the
47 to operate in interactive mode.
49 will be written to the standard output and commands read from the
52 Obtain a list of peers which are known to the server(s).
54 switch is equivalent to
57 Output all host addresses in dotted-quad numeric format rather
58 than converting to the canonical host names.
60 Print a list of the peers known to the server as well as a
61 summary of their state.
65 Print a list of the peers known to the server as well as a
66 summary of their state, but in a slightly different format than the
73 If one or more request options are included on the command line
76 is executed, each of the requests will be sent
77 to the NTP servers running on each of the hosts given as command
78 line arguments, or on localhost by default.
82 will attempt to read commands from the
83 standard input and execute these on the NTP server running on the
84 first host given on the command line, again defaulting to localhost
85 when no other host is specified.
88 utility will prompt for
89 commands if the standard input is a terminal device.
93 utility uses NTP mode 7 packets to communicate with the
94 NTP server, and hence can be used to query any compatible server on
95 the network which permits it.
96 Note that since NTP is a UDP protocol
97 this communication will be somewhat unreliable, especially over
98 large distances in terms of network topology.
102 no attempt to retransmit requests, and will time requests out if
103 the remote host is not heard from within a suitable timeout
108 are specific to the particular
109 implementation of the
111 daemon and can be expected to
112 work only with this and maybe some previous versions of the daemon.
113 Requests from a remote
115 utility which affect the
116 state of the local server must be authenticated, which requires
117 both the remote program and local server share a common key and key
119 Specifying a command line option other than
123 will cause the specified query (queries) to be sent to
124 the indicated host(s) immediately.
128 attempt to read interactive format commands from the standard
130 .Ss "Interactive Commands"
131 Interactive format commands consist of a keyword followed by zero
133 Only enough characters of the full keyword to
134 uniquely identify the command need be typed.
136 command is normally sent to the standard output, but optionally the
137 output of individual commands may be sent to a file by appending a
139 followed by a file name, to the command line.
141 A number of interactive format commands are executed entirely
144 utility itself and do not result in NTP
145 mode 7 requests being sent to a server.
148 .Bl -tag -width indent
149 .It Ic \&? Ar command_keyword
150 .It Ic help Ar command_keyword
153 will print a list of all the command
154 keywords known to this incarnation of
158 followed by a command keyword will print function and usage
159 information about the command.
160 This command is probably a better
161 source of information about
165 .It Ic delay Ar milliseconds
166 Specify a time interval to be added to timestamps included in
167 requests which require authentication.
168 This is used to enable
169 (unreliable) server reconfiguration over long delay network paths
170 or between machines whose clocks are unsynchronized.
172 server does not now require timestamps in authenticated requests,
173 so this command may be obsolete.
174 .It Ic host Ar hostname
175 Set the host to which future queries will be sent.
177 be either a host name or a numeric address.
178 .It Ic hostnames Op Cm yes | Cm no
181 is specified, host names are printed in
182 information displays.
185 is specified, numeric
186 addresses are printed instead.
190 modified using the command line
193 .It Ic keyid Ar keyid
194 This command allows the specification of a key number to be
195 used to authenticate configuration requests.
197 to a key number the server has been configured to use for this
203 This command prompts you to type in a password (which will not
204 be echoed) which will be used to authenticate configuration
206 The password must correspond to the key configured for
207 use by the NTP server for this purpose if such requests are to be
209 .It Ic timeout Ar milliseconds
210 Specify a timeout period for responses to server queries.
212 default is about 8000 milliseconds.
215 retries each query once after a timeout, the total waiting time for
216 a timeout will be twice the timeout value set.
218 .Ss "Control Message Commands"
219 Query commands result in NTP mode 7 packets containing requests for
220 information being sent to the server.
221 These are read-only commands
222 in that they make no modification of the server configuration
224 .Bl -tag -width indent
226 Obtains and prints a brief list of the peers for which the
227 server is maintaining state.
228 These should include all configured
229 peer associations as well as those peers whose stratum is such that
230 they are considered by the server to be possible future
231 synchonization candidates.
233 Obtains a list of peers for which the server is maintaining
234 state, along with a summary of that state.
236 includes the address of the remote peer, the local interface
237 address (0.0.0.0 if a local address has yet to be determined), the
238 stratum of the remote peer (a stratum of 16 indicates the remote
239 peer is unsynchronized), the polling interval, in seconds, the
240 reachability register, in octal, and the current estimated delay,
241 offset and dispersion of the peer, all in seconds.
243 The character in the left margin indicates the mode this peer
244 entry is operating in.
247 denotes symmetric active, a
249 indicates symmetric passive, a
252 remote server is being polled in client mode, a
254 indicates that the server is broadcasting to this address, a
256 denotes that the remote peer is sending broadcasts and a
258 marks the peer the server is currently synchronizing
261 The contents of the host field may be one of four forms.
263 be a host name, an IP address, a reference clock implementation
264 name with its parameter or
265 .Fn REFCLK "implementation_number" "parameter" .
272 A slightly different peer summary list.
273 Identical to the output
276 command, except for the character in the
278 Characters only appear beside peers which were
279 included in the final stage of the clock selection algorithm.
282 indicates that this peer was cast off in the falseticker
285 indicates that the peer made it
289 denotes the peer the server is currently
291 .It Ic showpeer Ar peer_address ...
292 Shows a detailed display of the current peer variables for one
294 Most of these values are described in the NTP
295 Version 2 specification.
296 .It Ic pstats Ar peer_address ...
297 Show per-peer statistic counters associated with the specified
299 .It Ic clockinfo Ar clock_peer_address ...
300 Obtain and print information concerning a peer clock.
302 values obtained provide information on the setting of fudge factors
303 and other clock performance information.
305 Obtain and print kernel phase-lock loop operating parameters.
306 This information is available only if the kernel has been specially
307 modified for a precision timekeeping function.
308 .It Ic loopinfo Op Cm oneline | Cm multiline
309 Print the values of selected loop filter variables.
311 filter is the part of NTP which deals with adjusting the local
315 is the last offset given to the
316 loop filter by the packet processing code.
319 is the frequency error of the local clock in parts-per-million
323 controls the stiffness of the
324 phase-lock loop and thus the speed at which it can adapt to
329 of seconds which have elapsed since the last sample offset was
330 given to the loop filter.
335 options specify the format in which this
336 information is to be printed, with
341 Print a variety of system state variables, i.e., state related
343 All except the last four lines are described
344 in the NTP Version 3 specification, RFC-1305.
348 show various system flags, some of
349 which can be set and cleared by the
353 configuration commands, respectively.
366 documentation for the meaning of these flags.
368 are two additional flags which are read only, the
373 the synchronization status when the precision time kernel
374 modifications are in use.
378 the local clock is being disciplined by the kernel, while the
380 indicates the kernel discipline is provided by the PPS
385 is the residual frequency error remaining
386 after the system frequency correction is applied and is intended for
387 maintenance and debugging.
388 In most architectures, this value will
389 initially decrease from as high as 500 ppm to a nominal value in
390 the range .01 to 0.1 ppm.
391 If it remains high for some time after
392 starting the daemon, something may be wrong with the local clock,
393 or the value of the kernel variable
394 .Va kern.clockrate.tick
400 shows the default broadcast delay,
403 configuration command.
407 shows the default authentication delay,
410 configuration command.
412 Print statistics counters maintained in the protocol
415 Print statistics counters related to memory allocation
418 Print statistics counters maintained in the input-output
421 Print statistics counters maintained in the timer/event queue
424 Obtain and print the server's restriction list.
426 (usually) printed in sorted order and may help to understand how
427 the restrictions are applied.
428 .It Ic monlist Op Ar version
429 Obtain and print traffic counts collected and maintained by the
431 The version number should not normally need to be
433 .It Ic clkbug Ar clock_peer_address ...
434 Obtain debugging information for a reference clock driver.
436 information is provided only by some clock drivers and is mostly
437 undecodable without a copy of the driver source in hand.
439 .Ss "Runtime Configuration Requests"
440 All requests which cause state changes in the server are
441 authenticated by the server using a configured NTP key (the
442 facility can also be disabled by the server by not configuring a
444 The key number and the corresponding key must also be made
447 This can be done using the
451 commands, the latter of which will prompt at the terminal for a
452 password to use as the encryption key.
453 You will also be prompted
454 automatically for both the key number and password the first time a
455 command which would result in an authenticated request to the
457 Authentication not only provides verification that
458 the requester has permission to make such changes, but also gives
459 an extra degree of protection again transmission errors.
461 Authenticated requests always include a timestamp in the packet
462 data, which is included in the computation of the authentication
464 This timestamp is compared by the server to its receive time
466 If they differ by more than a small amount the request is
468 This is done for two reasons.
469 First, it makes simple
470 replay attacks on the server, by someone who might be able to
471 overhear traffic on your LAN, much more difficult.
473 it more difficult to request configuration changes to your server
474 from topologically remote hosts.
475 While the reconfiguration facility
476 will work well with a server on the local host, and may work
477 adequately between time-synchronized hosts on the same LAN, it will
478 work very poorly for more distant hosts.
479 As such, if reasonable
480 passwords are chosen, care is taken in the distribution and
481 protection of keys and appropriate source address restrictions are
482 applied, the run time reconfiguration facility should provide an
483 adequate level of security.
485 The following commands all make authenticated requests.
486 .Bl -tag -width indent
487 .It Xo Ic addpeer Ar peer_address
492 Add a configured peer association at the given address and
493 operating in symmetric active mode.
494 Note that an existing
495 association with the same peer may be deleted when this command is
496 executed, or may simply be converted to conform to the new
497 configuration, as appropriate.
501 nonzero integer, all outgoing packets to the remote server will
502 have an authentication field attached encrypted with this key.
504 the value is 0 (or not given) no authentication will be done.
507 can be 1, 2 or 3 and defaults to 3.
510 keyword indicates a preferred peer (and thus will
511 be used primarily for clock synchronisation if possible).
513 preferred peer also determines the validity of the PPS signal - if
514 the preferred peer is suitable for synchronisation so is the PPS
516 .It Xo Ic addserver Ar peer_address
521 Identical to the addpeer command, except that the operating
523 .It Xo Ic broadcast Ar peer_address
528 Identical to the addpeer command, except that the operating
530 In this case a valid key identifier and key are
534 parameter can be the broadcast
535 address of the local network or a multicast group address assigned
537 If a multicast address, a multicast-capable kernel is
539 .It Ic unconfig Ar peer_address ...
540 This command causes the configured bit to be removed from the
542 In many cases this will cause the peer
543 association to be deleted.
544 When appropriate, however, the
545 association may persist in an unconfigured mode if the remote peer
546 is willing to continue on in this fashion.
547 .It Xo Ic fudge Ar peer_address
553 This command provides a way to set certain data for a reference
555 See the source listing for further information.
556 .It Ic enable Ar flag ...
557 .It Ic disable Ar flag ...
558 These commands operate in the same way as the
562 configuration file commands of
564 Following is a description of the flags.
581 .Bl -tag -width indent
583 Enables the server to synchronize with unconfigured peers only
584 if the peer has been correctly authenticated using a trusted key
586 The default for this flag is enable.
588 Enables the server to listen for a message from a broadcast or
589 multicast server, as in the
593 The default for this flag is disable.
595 Enables the monitoring facility.
598 command for further information.
600 default for this flag is enable.
602 Enables the server to adjust its local clock by means of NTP.
603 If disabled, the local clock free-runs at its intrinsic time and
605 This flag is useful in case the local clock is
606 controlled by some other device or protocol and NTP is used only to
607 provide synchronization to other clients.
608 In this case, the local
609 clock driver is used.
611 .Qq "Reference Clock Drivers"
613 (available as part of the HTML documentation
615 .Pa /usr/share/doc/ntp )
616 page for further information.
620 Enables the pulse-per-second (PPS) signal when frequency and
621 time is disciplined by the precision time kernel modifications.
624 .Qq "A Kernel Model for Precision Timekeeping"
625 page for further information.
626 The default for this flag is
629 Enables the statistics facility.
631 .Sx Monitoring Options
635 page for further information.
636 The default for this flag is enable.
638 When the precision time kernel modifications are installed,
639 this indicates the kernel controls the clock discipline; otherwise,
640 the daemon controls the clock discipline.
642 When the precision time kernel modifications are installed and
643 a pulse-per-second (PPS) signal is available, this indicates the
644 PPS signal controls the clock discipline; otherwise, the daemon or
645 kernel controls the clock discipline, as indicated by the
649 .It Xo Ic restrict Ar address Ar mask
652 This command operates in the same way as the
654 configuration file commands of
656 .It Xo Ic unrestrict Ar address Ar mask
659 Unrestrict the matching entry from the restrict list.
660 .It Xo Ic delrestrict Ar address Ar mask
663 Delete the matching entry from the restrict list.
665 Causes the current set of authentication keys to be purged and
666 a new set to be obtained by rereading the keys file (which must
667 have been specified in the
671 allows encryption keys to be changed without restarting the
673 .It Ic trustedkey Ar keyid ...
674 .It Ic untrustedkey Ar keyid ...
675 These commands operate in the same way as the
683 Returns information concerning the authentication module,
684 including known keys and counts of encryptions and decryptions
685 which have been done.
687 Display the traps set in the server.
688 See the source listing for
690 .It Xo Ic addtrap Ar address
694 Set a trap for asynchronous messages.
695 See the source listing
696 for further information.
697 .It Xo Ic clrtrap Ar address
701 Clear a trap for asynchronous messages.
702 See the source listing
703 for further information.
705 Clear the statistics counters in various modules of the server.
706 See the source listing for further information.
713 .%T Network Time Protocol (Version 3)
719 utility is a crude hack.
720 Much of the information it shows is
721 deadly boring and could only be loved by its implementer.
723 program was designed so that new (and temporary) features were easy
724 to hack in, at great expense to the program's ease of use.
726 this, the program is occasionally useful.