2 .Dt NTPDC 8 User Commands
4 .\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.mdoc)
8 .\" It has been AutoGen-ed January 7, 2016 at 11:31:29 PM by AutoGen 5.18.5
9 .\" From the definitions ntpdc-opts.def
10 .\" and the template file agmdoc-cmd.tpl
13 .Nd vendor-specific NTPD control program
16 .\" Mixture of short (flag) options and long options
18 .Op Fl flag Op Ar value
19 .Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
26 .Xr ntpq 8 instead \- it can do everything
28 used to do, and it does so using a much more sane interface.
31 is a utility program used to query
34 current state and to request changes in that state.
35 It uses NTP mode 7 control message formats described in the source code.
37 be run either in interactive mode or controlled using command line
39 Extensive state and statistics information is available
43 In addition, nearly all the
44 configuration options which can be specified at startup using
45 ntpd's configuration file may also be specified at run time using
50 Force IPv4 DNS name resolution.
51 This option must not appear in combination with any of the following options:
54 Force DNS resolution of following host names on the command line
55 to the IPv4 namespace.
57 Force IPv6 DNS name resolution.
58 This option must not appear in combination with any of the following options:
61 Force DNS resolution of following host names on the command line
62 to the IPv6 namespace.
63 .It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd
64 run a command and exit.
65 This option may appear an unlimited number of times.
67 The following argument is interpreted as an interactive format command
68 and is added to the list of commands to be executed on the specified
70 .It Fl d , Fl \-debug\-level
71 Increase debug verbosity level.
72 This option may appear an unlimited number of times.
74 .It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
75 Set the debug verbosity level.
76 This option may appear an unlimited number of times.
77 This option takes an integer number as its argument.
79 .It Fl i , Fl \-interactive
80 Force ntpq to operate in interactive mode.
81 This option must not appear in combination with any of the following options:
82 command, listpeers, peers, showpeers.
84 Force ntpq to operate in interactive mode. Prompts will be written
85 to the standard output and commands read from the standard input.
86 .It Fl l , Fl \-listpeers
87 Print a list of the peers.
88 This option must not appear in combination with any of the following options:
91 Print a list of the peers known to the server as well as a summary of
92 their state. This is equivalent to the 'listpeers' interactive command.
93 .It Fl n , Fl \-numeric
94 numeric host addresses.
96 Output all host addresses in dotted\-quad numeric format rather than
97 converting to the canonical host names.
99 Print a list of the peers.
100 This option must not appear in combination with any of the following options:
103 Print a list of the peers known to the server as well as a summary
104 of their state. This is equivalent to the 'peers' interactive command.
105 .It Fl s , Fl \-showpeers
106 Show a list of the peers.
107 This option must not appear in combination with any of the following options:
110 Print a list of the peers known to the server as well as a summary
111 of their state. This is equivalent to the 'dmpeers' interactive command.
112 .It Fl \&? , Fl \-help
113 Display usage information and exit.
114 .It Fl \&! , Fl \-more\-help
115 Pass the extended usage information through a pager.
116 .It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
117 Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP
118 configuration file listed in the \fBOPTION PRESETS\fP section, below.
119 The command will exit after updating the config file.
120 .It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
121 Load options from \fIcfgfile\fP.
122 The \fIno\-load\-opts\fP form will disable the loading
123 of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early,
125 .It Fl \-version Op Brq Ar v|c|n
126 Output version of program and exit. The default mode is `v', a simple
127 version. The `c' mode will print copyright information and `n' will
128 print the full copyright notice.
131 Any option that is not marked as \fInot presettable\fP may be preset
132 by loading values from configuration ("RC" or ".INI") file(s) and values from
133 environment variables named:
135 \fBNTPDC_<option\-name>\fP or \fBNTPDC\fP
138 The environmental presets take precedence (are processed later than)
139 the configuration files.
140 The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
141 If any of these are directories, then the file \fI.ntprc\fP
142 is searched for within those directories.
144 If one or more request options are included on the command line
147 is executed, each of the requests will be sent
148 to the NTP servers running on each of the hosts given as command
149 line arguments, or on localhost by default.
150 If no request options
153 will attempt to read commands from the
154 standard input and execute these on the NTP server running on the
155 first host given on the command line, again defaulting to localhost
156 when no other host is specified.
159 utility will prompt for
160 commands if the standard input is a terminal device.
164 utility uses NTP mode 7 packets to communicate with the
165 NTP server, and hence can be used to query any compatible server on
166 the network which permits it.
167 Note that since NTP is a UDP protocol
168 this communication will be somewhat unreliable, especially over
169 large distances in terms of network topology.
173 no attempt to retransmit requests, and will time requests out if
174 the remote host is not heard from within a suitable timeout
179 are specific to the particular
180 implementation of the
182 daemon and can be expected to
183 work only with this and maybe some previous versions of the daemon.
184 Requests from a remote
186 utility which affect the
187 state of the local server must be authenticated, which requires
188 both the remote program and local server share a common key and key
191 Note that in contexts where a host name is expected, a
193 qualifier preceding the host name forces DNS resolution to the IPv4 namespace,
196 qualifier forces DNS resolution to the IPv6 namespace.
197 Specifying a command line option other than
201 will cause the specified query (queries) to be sent to
202 the indicated host(s) immediately.
206 attempt to read interactive format commands from the standard
208 .Ss "Interactive Commands"
209 Interactive format commands consist of a keyword followed by zero
211 Only enough characters of the full keyword to
212 uniquely identify the command need be typed.
214 command is normally sent to the standard output, but optionally the
215 output of individual commands may be sent to a file by appending a
217 followed by a file name, to the command line.
219 A number of interactive format commands are executed entirely
222 utility itself and do not result in NTP
223 mode 7 requests being sent to a server.
226 .Bl -tag -width indent
227 .It Ic \&? Ar command_keyword
228 .It Ic help Ar command_keyword
231 will print a list of all the command
232 keywords known to this incarnation of
236 followed by a command keyword will print function and usage
237 information about the command.
238 This command is probably a better
239 source of information about
243 .It Ic delay Ar milliseconds
244 Specify a time interval to be added to timestamps included in
245 requests which require authentication.
246 This is used to enable
247 (unreliable) server reconfiguration over long delay network paths
248 or between machines whose clocks are unsynchronized.
250 server does not now require timestamps in authenticated requests,
251 so this command may be obsolete.
252 .It Ic host Ar hostname
253 Set the host to which future queries will be sent.
255 be either a host name or a numeric address.
256 .It Ic hostnames Op Cm yes | Cm no
259 is specified, host names are printed in
260 information displays.
263 is specified, numeric
264 addresses are printed instead.
268 modified using the command line
271 .It Ic keyid Ar keyid
272 This command allows the specification of a key number to be
273 used to authenticate configuration requests.
275 to a key number the server has been configured to use for this
281 This command prompts you to type in a password (which will not
282 be echoed) which will be used to authenticate configuration
284 The password must correspond to the key configured for
285 use by the NTP server for this purpose if such requests are to be
287 .It Ic timeout Ar milliseconds
288 Specify a timeout period for responses to server queries.
290 default is about 8000 milliseconds.
293 retries each query once after a timeout, the total waiting time for
294 a timeout will be twice the timeout value set.
296 .Ss "Control Message Commands"
297 Query commands result in NTP mode 7 packets containing requests for
298 information being sent to the server.
299 These are read\-only commands
300 in that they make no modification of the server configuration
302 .Bl -tag -width indent
304 Obtains and prints a brief list of the peers for which the
305 server is maintaining state.
306 These should include all configured
307 peer associations as well as those peers whose stratum is such that
308 they are considered by the server to be possible future
309 synchronization candidates.
311 Obtains a list of peers for which the server is maintaining
312 state, along with a summary of that state.
314 includes the address of the remote peer, the local interface
315 address (0.0.0.0 if a local address has yet to be determined), the
316 stratum of the remote peer (a stratum of 16 indicates the remote
317 peer is unsynchronized), the polling interval, in seconds, the
318 reachability register, in octal, and the current estimated delay,
319 offset and dispersion of the peer, all in seconds.
321 The character in the left margin indicates the mode this peer
322 entry is operating in.
325 denotes symmetric active, a
327 indicates symmetric passive, a
330 remote server is being polled in client mode, a
332 indicates that the server is broadcasting to this address, a
334 denotes that the remote peer is sending broadcasts and a
336 denotes that the remote peer is sending broadcasts and a
338 marks the peer the server is currently synchronizing
341 The contents of the host field may be one of four forms.
343 be a host name, an IP address, a reference clock implementation
344 name with its parameter or
345 .Fn REFCLK "implementation_number" "parameter" .
352 A slightly different peer summary list.
353 Identical to the output
356 command, except for the character in the
358 Characters only appear beside peers which were
359 included in the final stage of the clock selection algorithm.
362 indicates that this peer was cast off in the falseticker
365 indicates that the peer made it
369 denotes the peer the server is currently
371 .It Ic showpeer Ar peer_address Oo Ar ... Oc
372 Shows a detailed display of the current peer variables for one
374 Most of these values are described in the NTP
375 Version 2 specification.
376 .It Ic pstats Ar peer_address Oo Ar ... Oc
377 Show per\-peer statistic counters associated with the specified
379 .It Ic clockstat Ar clock_peer_address Oo Ar ... Oc
380 Obtain and print information concerning a peer clock.
382 values obtained provide information on the setting of fudge factors
383 and other clock performance information.
385 Obtain and print kernel phase\-lock loop operating parameters.
386 This information is available only if the kernel has been specially
387 modified for a precision timekeeping function.
388 .It Ic loopinfo Op Cm oneline | Cm multiline
389 Print the values of selected loop filter variables.
391 filter is the part of NTP which deals with adjusting the local
395 is the last offset given to the
396 loop filter by the packet processing code.
399 is the frequency error of the local clock in parts\-per\-million
403 controls the stiffness of the
404 phase\-lock loop and thus the speed at which it can adapt to
409 of seconds which have elapsed since the last sample offset was
410 given to the loop filter.
415 options specify the format in which this
416 information is to be printed, with
421 Print a variety of system state variables, i.e., state related
423 All except the last four lines are described
424 in the NTP Version 3 specification, RFC\-1305.
428 show various system flags, some of
429 which can be set and cleared by the
433 configuration commands, respectively.
446 documentation for the meaning of these flags.
448 are two additional flags which are read only, the
453 the synchronization status when the precision time kernel
454 modifications are in use.
458 the local clock is being disciplined by the kernel, while the
460 indicates the kernel discipline is provided by the PPS
465 is the residual frequency error remaining
466 after the system frequency correction is applied and is intended for
467 maintenance and debugging.
468 In most architectures, this value will
469 initially decrease from as high as 500 ppm to a nominal value in
470 the range .01 to 0.1 ppm.
471 If it remains high for some time after
472 starting the daemon, something may be wrong with the local clock,
473 or the value of the kernel variable
474 .Va kern.clockrate.tick
480 shows the default broadcast delay,
483 configuration command.
487 shows the default authentication delay,
490 configuration command.
492 Print statistics counters maintained in the protocol
495 Print statistics counters related to memory allocation
498 Print statistics counters maintained in the input\-output
501 Print statistics counters maintained in the timer/event queue
504 Obtain and print the server's restriction list.
506 (usually) printed in sorted order and may help to understand how
507 the restrictions are applied.
508 .It Ic monlist Op Ar version
509 Obtain and print traffic counts collected and maintained by the
511 The version number should not normally need to be
513 .It Ic clkbug Ar clock_peer_address Oo Ar ... Oc
514 Obtain debugging information for a reference clock driver.
516 information is provided only by some clock drivers and is mostly
517 undecodable without a copy of the driver source in hand.
519 .Ss "Runtime Configuration Requests"
520 All requests which cause state changes in the server are
521 authenticated by the server using a configured NTP key (the
522 facility can also be disabled by the server by not configuring a
524 The key number and the corresponding key must also be made
527 This can be done using the
531 commands, the latter of which will prompt at the terminal for a
532 password to use as the encryption key.
533 You will also be prompted
534 automatically for both the key number and password the first time a
535 command which would result in an authenticated request to the
537 Authentication not only provides verification that
538 the requester has permission to make such changes, but also gives
539 an extra degree of protection again transmission errors.
541 Authenticated requests always include a timestamp in the packet
542 data, which is included in the computation of the authentication
544 This timestamp is compared by the server to its receive time
546 If they differ by more than a small amount the request is
548 This is done for two reasons.
549 First, it makes simple
550 replay attacks on the server, by someone who might be able to
551 overhear traffic on your LAN, much more difficult.
553 it more difficult to request configuration changes to your server
554 from topologically remote hosts.
555 While the reconfiguration facility
556 will work well with a server on the local host, and may work
557 adequately between time\-synchronized hosts on the same LAN, it will
558 work very poorly for more distant hosts.
559 As such, if reasonable
560 passwords are chosen, care is taken in the distribution and
561 protection of keys and appropriate source address restrictions are
562 applied, the run time reconfiguration facility should provide an
563 adequate level of security.
565 The following commands all make authenticated requests.
566 .Bl -tag -width indent
567 .It Xo Ic addpeer Ar peer_address
572 Add a configured peer association at the given address and
573 operating in symmetric active mode.
574 Note that an existing
575 association with the same peer may be deleted when this command is
576 executed, or may simply be converted to conform to the new
577 configuration, as appropriate.
581 nonzero integer, all outgoing packets to the remote server will
582 have an authentication field attached encrypted with this key.
584 the value is 0 (or not given) no authentication will be done.
587 can be 1, 2 or 3 and defaults to 3.
590 keyword indicates a preferred peer (and thus will
591 be used primarily for clock synchronisation if possible).
593 preferred peer also determines the validity of the PPS signal \- if
594 the preferred peer is suitable for synchronisation so is the PPS
596 .It Xo Ic addserver Ar peer_address
601 Identical to the addpeer command, except that the operating
603 .It Xo Ic broadcast Ar peer_address
608 Identical to the addpeer command, except that the operating
610 In this case a valid key identifier and key are
614 parameter can be the broadcast
615 address of the local network or a multicast group address assigned
617 If a multicast address, a multicast\-capable kernel is
619 .It Ic unconfig Ar peer_address Oo Ar ... Oc
620 This command causes the configured bit to be removed from the
622 In many cases this will cause the peer
623 association to be deleted.
624 When appropriate, however, the
625 association may persist in an unconfigured mode if the remote peer
626 is willing to continue on in this fashion.
627 .It Xo Ic fudge Ar peer_address
633 This command provides a way to set certain data for a reference
635 See the source listing for further information.
638 .Cm auth | Cm bclient |
639 .Cm calibrate | Cm kernel |
640 .Cm monitor | Cm ntp |
646 .Cm auth | Cm bclient |
647 .Cm calibrate | Cm kernel |
648 .Cm monitor | Cm ntp |
652 These commands operate in the same way as the
656 configuration file commands of
658 .Bl -tag -width indent
660 Enables the server to synchronize with unconfigured peers only
661 if the peer has been correctly authenticated using either public key
662 or private key cryptography.
663 The default for this flag is enable.
665 Enables the server to listen for a message from a broadcast or
666 multicast server, as in the multicastclient command with
668 The default for this flag is disable.
670 Enables the calibrate feature for reference clocks.
671 The default for this flag is disable.
673 Enables the kernel time discipline, if available.
674 The default for this flag is enable if support is available, otherwise disable.
676 Enables the monitoring facility.
677 See the documentation here about the
679 command or further information.
680 The default for this flag is enable.
682 Enables time and frequency discipline.
683 In effect, this switch opens and closes the feedback loop,
684 which is useful for testing.
685 The default for this flag is enable.
687 Enables the pulse\-per\-second (PPS) signal when frequency
688 and time is disciplined by the precision time kernel modifications.
690 .Qq A Kernel Model for Precision Timekeeping
691 (available as part of the HTML documentation
693 .Pa /usr/share/doc/ntp )
694 page for further information.
695 The default for this flag is disable.
697 Enables the statistics facility.
699 .Sx Monitoring Options
702 for further information.
703 The default for this flag is disable.
705 .It Xo Ic restrict Ar address Ar mask
706 .Ar flag Oo Ar ... Oc
708 This command operates in the same way as the
710 configuration file commands of
712 .It Xo Ic unrestrict Ar address Ar mask
713 .Ar flag Oo Ar ... Oc
715 Unrestrict the matching entry from the restrict list.
716 .It Xo Ic delrestrict Ar address Ar mask
719 Delete the matching entry from the restrict list.
721 Causes the current set of authentication keys to be purged and
722 a new set to be obtained by rereading the keys file (which must
723 have been specified in the
727 allows encryption keys to be changed without restarting the
729 .It Ic trustedkey Ar keyid Oo Ar ... Oc
730 .It Ic untrustedkey Ar keyid Oo Ar ... Oc
731 These commands operate in the same way as the
739 Returns information concerning the authentication module,
740 including known keys and counts of encryptions and decryptions
741 which have been done.
743 Display the traps set in the server.
744 See the source listing for
746 .It Xo Ic addtrap Ar address
750 Set a trap for asynchronous messages.
751 See the source listing
752 for further information.
753 .It Xo Ic clrtrap Ar address
757 Clear a trap for asynchronous messages.
758 See the source listing
759 for further information.
761 Clear the statistics counters in various modules of the server.
762 See the source listing for further information.
765 See \fBOPTION PRESETS\fP for configuration environment variables.
767 See \fBOPTION PRESETS\fP for configuration files.
769 One of the following exit values will be returned:
771 .It 0 " (EXIT_SUCCESS)"
772 Successful program execution.
773 .It 1 " (EXIT_FAILURE)"
774 The operation failed or the command syntax was not valid.
775 .It 66 " (EX_NOINPUT)"
776 A specified configuration file could not be loaded.
777 .It 70 " (EX_SOFTWARE)"
778 libopts had an internal operational error. Please report
779 it to autogen\-users@lists.sourceforge.net. Thank you.
786 .%T Network Time Protocol (Version 3)
790 The formatting directives in this document came from FreeBSD.
792 Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved.
793 This program is released under the terms of the NTP license, <http://ntp.org/license>.
797 utility is a crude hack.
798 Much of the information it shows is
799 deadly boring and could only be loved by its implementer.
801 program was designed so that new (and temporary) features were easy
802 to hack in, at great expense to the program's ease of use.
804 this, the program is occasionally useful.
806 Please report bugs to http://bugs.ntp.org .
808 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
810 This manual page was \fIAutoGen\fP\-erated from the \fBntpdc\fP