1 /* -*- Mode: Text -*- */
3 autogen definitions options;
5 #include autogen-version.def
9 prog-title = "vendor-specific NTPD control program";
10 argument = '[ host ...]';
18 descrip = "Force IPv4 DNS name resolution";
20 Force DNS resolution of following host names on the command line
21 to the IPv4 namespace.
29 descrip = "Force IPv6 DNS name resolution";
31 Force DNS resolution of following host names on the command line
32 to the IPv6 namespace.
40 descrip = "run a command and exit";
45 The following argument is interpreted as an interactive format command
46 and is added to the list of commands to be executed on the specified
51 #include debug-opt.def
56 flags-cant = command, listpeers, peers, showpeers;
57 descrip = "Force ntpq to operate in interactive mode";
59 Force ntpq to operate in interactive mode. Prompts will be written
60 to the standard output and commands read from the standard input.
67 descrip = "Print a list of the peers";
70 Print a list of the peers known to the server as well as a summary of
71 their state. This is equivalent to the 'listpeers' interactive command.
78 descrip = "numeric host addresses";
80 Output all host addresses in dotted-quad numeric format rather than
81 converting to the canonical host names.
88 descrip = "Print a list of the peers";
91 Print a list of the peers known to the server as well as a summary
92 of their state. This is equivalent to the 'peers' interactive command.
99 descrip = "Show a list of the peers";
100 flags-cant = command;
102 Print a list of the peers known to the server as well as a summary
103 of their state. This is equivalent to the 'dmpeers' interactive command.
107 /* explain: Additional information whenever the usage routine is invoked */
108 explain = <<- _END_EXPLAIN
112 ds-type = 'DESCRIPTION';
114 ds-text = <<- _END_PROG_MDOC_DESCRIP
118 .Xr ntpq 1ntpqmdoc instead - it can do everything
120 used to do, and it does so using a much more sane interface.
123 is a utility program used to query
126 current state and to request changes in that state.
127 It uses NTP mode 7 control message formats described in the source code.
129 be run either in interactive mode or controlled using command line
131 Extensive state and statistics information is available
135 In addition, nearly all the
136 configuration options which can be specified at startup using
137 ntpd's configuration file may also be specified at run time using
139 _END_PROG_MDOC_DESCRIP;
146 ds-text = <<- _END_MDOC_USAGE
147 If one or more request options are included on the command line
150 is executed, each of the requests will be sent
151 to the NTP servers running on each of the hosts given as command
152 line arguments, or on localhost by default.
153 If no request options
156 will attempt to read commands from the
157 standard input and execute these on the NTP server running on the
158 first host given on the command line, again defaulting to localhost
159 when no other host is specified.
162 utility will prompt for
163 commands if the standard input is a terminal device.
167 utility uses NTP mode 7 packets to communicate with the
168 NTP server, and hence can be used to query any compatible server on
169 the network which permits it.
170 Note that since NTP is a UDP protocol
171 this communication will be somewhat unreliable, especially over
172 large distances in terms of network topology.
176 no attempt to retransmit requests, and will time requests out if
177 the remote host is not heard from within a suitable timeout
182 are specific to the particular
183 implementation of the
185 daemon and can be expected to
186 work only with this and maybe some previous versions of the daemon.
187 Requests from a remote
189 utility which affect the
190 state of the local server must be authenticated, which requires
191 both the remote program and local server share a common key and key
194 Note that in contexts where a host name is expected, a
196 qualifier preceding the host name forces DNS resolution to the IPv4 namespace,
199 qualifier forces DNS resolution to the IPv6 namespace.
200 Specifying a command line option other than
204 will cause the specified query (queries) to be sent to
205 the indicated host(s) immediately.
209 attempt to read interactive format commands from the standard
211 .Ss "Interactive Commands"
212 Interactive format commands consist of a keyword followed by zero
214 Only enough characters of the full keyword to
215 uniquely identify the command need be typed.
217 command is normally sent to the standard output, but optionally the
218 output of individual commands may be sent to a file by appending a
220 followed by a file name, to the command line.
222 A number of interactive format commands are executed entirely
225 utility itself and do not result in NTP
226 mode 7 requests being sent to a server.
229 .Bl -tag -width indent
230 .It Ic \&? Ar command_keyword
231 .It Ic help Ar command_keyword
234 will print a list of all the command
235 keywords known to this incarnation of
239 followed by a command keyword will print function and usage
240 information about the command.
241 This command is probably a better
242 source of information about
246 .It Ic delay Ar milliseconds
247 Specify a time interval to be added to timestamps included in
248 requests which require authentication.
249 This is used to enable
250 (unreliable) server reconfiguration over long delay network paths
251 or between machines whose clocks are unsynchronized.
253 server does not now require timestamps in authenticated requests,
254 so this command may be obsolete.
255 .It Ic host Ar hostname
256 Set the host to which future queries will be sent.
258 be either a host name or a numeric address.
259 .It Ic hostnames Op Cm yes | Cm no
262 is specified, host names are printed in
263 information displays.
266 is specified, numeric
267 addresses are printed instead.
271 modified using the command line
274 .It Ic keyid Ar keyid
275 This command allows the specification of a key number to be
276 used to authenticate configuration requests.
278 to a key number the server has been configured to use for this
284 This command prompts you to type in a password (which will not
285 be echoed) which will be used to authenticate configuration
287 The password must correspond to the key configured for
288 use by the NTP server for this purpose if such requests are to be
290 .It Ic timeout Ar milliseconds
291 Specify a timeout period for responses to server queries.
293 default is about 8000 milliseconds.
296 retries each query once after a timeout, the total waiting time for
297 a timeout will be twice the timeout value set.
299 .Ss "Control Message Commands"
300 Query commands result in NTP mode 7 packets containing requests for
301 information being sent to the server.
302 These are read-only commands
303 in that they make no modification of the server configuration
305 .Bl -tag -width indent
307 Obtains and prints a brief list of the peers for which the
308 server is maintaining state.
309 These should include all configured
310 peer associations as well as those peers whose stratum is such that
311 they are considered by the server to be possible future
312 synchronization candidates.
314 Obtains a list of peers for which the server is maintaining
315 state, along with a summary of that state.
317 includes the address of the remote peer, the local interface
318 address (0.0.0.0 if a local address has yet to be determined), the
319 stratum of the remote peer (a stratum of 16 indicates the remote
320 peer is unsynchronized), the polling interval, in seconds, the
321 reachability register, in octal, and the current estimated delay,
322 offset and dispersion of the peer, all in seconds.
324 The character in the left margin indicates the mode this peer
325 entry is operating in.
328 denotes symmetric active, a
330 indicates symmetric passive, a
333 remote server is being polled in client mode, a
335 indicates that the server is broadcasting to this address, a
337 denotes that the remote peer is sending broadcasts and a
339 denotes that the remote peer is sending broadcasts and a
341 marks the peer the server is currently synchronizing
344 The contents of the host field may be one of four forms.
346 be a host name, an IP address, a reference clock implementation
347 name with its parameter or
348 .Fn REFCLK "implementation_number" "parameter" .
355 A slightly different peer summary list.
356 Identical to the output
359 command, except for the character in the
361 Characters only appear beside peers which were
362 included in the final stage of the clock selection algorithm.
365 indicates that this peer was cast off in the falseticker
368 indicates that the peer made it
372 denotes the peer the server is currently
374 .It Ic showpeer Ar peer_address Oo Ar ... Oc
375 Shows a detailed display of the current peer variables for one
377 Most of these values are described in the NTP
378 Version 2 specification.
379 .It Ic pstats Ar peer_address Oo Ar ... Oc
380 Show per-peer statistic counters associated with the specified
382 .It Ic clockstat Ar clock_peer_address Oo Ar ... Oc
383 Obtain and print information concerning a peer clock.
385 values obtained provide information on the setting of fudge factors
386 and other clock performance information.
388 Obtain and print kernel phase-lock loop operating parameters.
389 This information is available only if the kernel has been specially
390 modified for a precision timekeeping function.
391 .It Ic loopinfo Op Cm oneline | Cm multiline
392 Print the values of selected loop filter variables.
394 filter is the part of NTP which deals with adjusting the local
398 is the last offset given to the
399 loop filter by the packet processing code.
402 is the frequency error of the local clock in parts-per-million
406 controls the stiffness of the
407 phase-lock loop and thus the speed at which it can adapt to
412 of seconds which have elapsed since the last sample offset was
413 given to the loop filter.
418 options specify the format in which this
419 information is to be printed, with
424 Print a variety of system state variables, i.e., state related
426 All except the last four lines are described
427 in the NTP Version 3 specification, RFC-1305.
431 show various system flags, some of
432 which can be set and cleared by the
436 configuration commands, respectively.
449 documentation for the meaning of these flags.
451 are two additional flags which are read only, the
456 the synchronization status when the precision time kernel
457 modifications are in use.
461 the local clock is being disciplined by the kernel, while the
463 indicates the kernel discipline is provided by the PPS
468 is the residual frequency error remaining
469 after the system frequency correction is applied and is intended for
470 maintenance and debugging.
471 In most architectures, this value will
472 initially decrease from as high as 500 ppm to a nominal value in
473 the range .01 to 0.1 ppm.
474 If it remains high for some time after
475 starting the daemon, something may be wrong with the local clock,
476 or the value of the kernel variable
477 .Va kern.clockrate.tick
483 shows the default broadcast delay,
486 configuration command.
490 shows the default authentication delay,
493 configuration command.
495 Print statistics counters maintained in the protocol
498 Print statistics counters related to memory allocation
501 Print statistics counters maintained in the input-output
504 Print statistics counters maintained in the timer/event queue
507 Obtain and print the server's restriction list.
509 (usually) printed in sorted order and may help to understand how
510 the restrictions are applied.
511 .It Ic monlist Op Ar version
512 Obtain and print traffic counts collected and maintained by the
514 The version number should not normally need to be
516 .It Ic clkbug Ar clock_peer_address Oo Ar ... Oc
517 Obtain debugging information for a reference clock driver.
519 information is provided only by some clock drivers and is mostly
520 undecodable without a copy of the driver source in hand.
522 .Ss "Runtime Configuration Requests"
523 All requests which cause state changes in the server are
524 authenticated by the server using a configured NTP key (the
525 facility can also be disabled by the server by not configuring a
527 The key number and the corresponding key must also be made
530 This can be done using the
534 commands, the latter of which will prompt at the terminal for a
535 password to use as the encryption key.
536 You will also be prompted
537 automatically for both the key number and password the first time a
538 command which would result in an authenticated request to the
540 Authentication not only provides verification that
541 the requester has permission to make such changes, but also gives
542 an extra degree of protection again transmission errors.
544 Authenticated requests always include a timestamp in the packet
545 data, which is included in the computation of the authentication
547 This timestamp is compared by the server to its receive time
549 If they differ by more than a small amount the request is
551 This is done for two reasons.
552 First, it makes simple
553 replay attacks on the server, by someone who might be able to
554 overhear traffic on your LAN, much more difficult.
556 it more difficult to request configuration changes to your server
557 from topologically remote hosts.
558 While the reconfiguration facility
559 will work well with a server on the local host, and may work
560 adequately between time-synchronized hosts on the same LAN, it will
561 work very poorly for more distant hosts.
562 As such, if reasonable
563 passwords are chosen, care is taken in the distribution and
564 protection of keys and appropriate source address restrictions are
565 applied, the run time reconfiguration facility should provide an
566 adequate level of security.
568 The following commands all make authenticated requests.
569 .Bl -tag -width indent
570 .It Xo Ic addpeer Ar peer_address
575 Add a configured peer association at the given address and
576 operating in symmetric active mode.
577 Note that an existing
578 association with the same peer may be deleted when this command is
579 executed, or may simply be converted to conform to the new
580 configuration, as appropriate.
584 nonzero integer, all outgoing packets to the remote server will
585 have an authentication field attached encrypted with this key.
587 the value is 0 (or not given) no authentication will be done.
590 can be 1, 2 or 3 and defaults to 3.
593 keyword indicates a preferred peer (and thus will
594 be used primarily for clock synchronisation if possible).
596 preferred peer also determines the validity of the PPS signal - if
597 the preferred peer is suitable for synchronisation so is the PPS
599 .It Xo Ic addserver Ar peer_address
604 Identical to the addpeer command, except that the operating
606 .It Xo Ic broadcast Ar peer_address
611 Identical to the addpeer command, except that the operating
613 In this case a valid key identifier and key are
617 parameter can be the broadcast
618 address of the local network or a multicast group address assigned
620 If a multicast address, a multicast-capable kernel is
622 .It Ic unconfig Ar peer_address Oo Ar ... Oc
623 This command causes the configured bit to be removed from the
625 In many cases this will cause the peer
626 association to be deleted.
627 When appropriate, however, the
628 association may persist in an unconfigured mode if the remote peer
629 is willing to continue on in this fashion.
630 .It Xo Ic fudge Ar peer_address
636 This command provides a way to set certain data for a reference
638 See the source listing for further information.
641 .Cm auth | Cm bclient |
642 .Cm calibrate | Cm kernel |
643 .Cm monitor | Cm ntp |
649 .Cm auth | Cm bclient |
650 .Cm calibrate | Cm kernel |
651 .Cm monitor | Cm ntp |
655 These commands operate in the same way as the
659 configuration file commands of
661 .Bl -tag -width indent
663 Enables the server to synchronize with unconfigured peers only
664 if the peer has been correctly authenticated using either public key
665 or private key cryptography.
666 The default for this flag is enable.
668 Enables the server to listen for a message from a broadcast or
669 multicast server, as in the multicastclient command with
671 The default for this flag is disable.
673 Enables the calibrate feature for reference clocks.
674 The default for this flag is disable.
676 Enables the kernel time discipline, if available.
677 The default for this flag is enable if support is available, otherwise disable.
679 Enables the monitoring facility.
680 See the documentation here about the
682 command or further information.
683 The default for this flag is enable.
685 Enables time and frequency discipline.
686 In effect, this switch opens and closes the feedback loop,
687 which is useful for testing.
688 The default for this flag is enable.
690 Enables the pulse-per-second (PPS) signal when frequency
691 and time is disciplined by the precision time kernel modifications.
693 .Qq A Kernel Model for Precision Timekeeping
694 (available as part of the HTML documentation
696 .Pa /usr/share/doc/ntp )
697 page for further information.
698 The default for this flag is disable.
700 Enables the statistics facility.
702 .Sx Monitoring Options
705 for further information.
706 The default for this flag is disable.
708 .It Xo Ic restrict Ar address Ar mask
709 .Ar flag Oo Ar ... Oc
711 This command operates in the same way as the
713 configuration file commands of
715 .It Xo Ic unrestrict Ar address Ar mask
716 .Ar flag Oo Ar ... Oc
718 Unrestrict the matching entry from the restrict list.
719 .It Xo Ic delrestrict Ar address Ar mask
722 Delete the matching entry from the restrict list.
724 Causes the current set of authentication keys to be purged and
725 a new set to be obtained by rereading the keys file (which must
726 have been specified in the
730 allows encryption keys to be changed without restarting the
732 .It Ic trustedkey Ar keyid Oo Ar ... Oc
733 .It Ic untrustedkey Ar keyid Oo Ar ... Oc
734 These commands operate in the same way as the
742 Returns information concerning the authentication module,
743 including known keys and counts of encryptions and decryptions
744 which have been done.
746 Display the traps set in the server.
747 See the source listing for
749 .It Xo Ic addtrap Ar address
753 Set a trap for asynchronous messages.
754 See the source listing
755 for further information.
756 .It Xo Ic clrtrap Ar address
760 Clear a trap for asynchronous messages.
761 See the source listing
762 for further information.
764 Clear the statistics counters in various modules of the server.
765 See the source listing for further information.
772 ds-type = 'SEE ALSO';
774 ds-text = <<- _END_MDOC_SEEALSO
779 .%T Network Time Protocol (Version 3)
789 ds-text = <<- _END_MDOC_AUTHORS
790 The formatting directives in this document came from FreeBSD.
798 ds-text = <<- _END_MDOC_BUGS
801 utility is a crude hack.
802 Much of the information it shows is
803 deadly boring and could only be loved by its implementer.
805 program was designed so that new (and temporary) features were easy
806 to hack in, at great expense to the program's ease of use.
808 this, the program is occasionally useful.
810 Please report bugs to http://bugs.ntp.org .