1.Dd June 23 2020
2.Dt NTPDC @NTPDC_MS@ User Commands
4.\"  EDIT THIS FILE WITH CAUTION  (ntpdc-opts.mdoc)
6.\"  It has been AutoGen-ed  June 23, 2020 at 02:20:44 AM by AutoGen 5.18.5
7.\"  From the definitions    ntpdc-opts.def
8.\"  and the template file   agmdoc-cmd.tpl
10.Nm ntpdc
11.Nd vendor-specific NTPD control program
14.\" Mixture of short (flag) options and long options
15.Op Fl flags
16.Op Fl flag Op Ar value
17.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
18[ host ...]
22is deprecated.
23Please use
24.Xr ntpq @NTPQ_MS@ instead \- it can do everything
26used to do, and it does so using a much more sane interface.
29is a utility program used to query
30.Xr ntpd @NTPD_MS@
31about its
32current state and to request changes in that state.
33It uses NTP mode 7 control message formats described in the source code.
34The program may
35be run either in interactive mode or controlled using command line
37Extensive state and statistics information is available
38through the
41In addition, nearly all the
42configuration options which can be specified at startup using
43ntpd's configuration file may also be specified at run time using
44.Nm .
46.Bl -tag
47.It  Fl 4 , Fl \-ipv4 
48Force IPv4 DNS name resolution.
49This option must not appear in combination with any of the following options:
52Force DNS resolution of following host names on the command line
53to the IPv4 namespace.
54.It  Fl 6 , Fl \-ipv6 
55Force IPv6 DNS name resolution.
56This option must not appear in combination with any of the following options:
59Force DNS resolution of following host names on the command line
60to the IPv6 namespace.
61.It  Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd 
62run a command and exit.
63This option may appear an unlimited number of times.
65The following argument is interpreted as an interactive format command
66and is added to the list of commands to be executed on the specified
68.It  Fl d , Fl \-debug\-level 
69Increase debug verbosity level.
70This option may appear an unlimited number of times.
72.It  Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 
73Set the debug verbosity level.
74This option may appear an unlimited number of times.
75This option takes an integer number as its argument.
77.It  Fl i , Fl \-interactive 
78Force ntpq to operate in interactive mode.
79This option must not appear in combination with any of the following options:
80command, listpeers, peers, showpeers.
82Force ntpq to operate in interactive mode.  Prompts will be written
83to the standard output and commands read from the standard input.
84.It  Fl l , Fl \-listpeers 
85Print a list of the peers.
86This option must not appear in combination with any of the following options:
89Print a list of the peers known to the server as well as a summary of
90their state. This is equivalent to the 'listpeers' interactive command.
91.It  Fl n , Fl \-numeric 
92numeric host addresses.
94Output all host addresses in dotted\-quad numeric format rather than
95converting to the canonical host names. 
96.It  Fl p , Fl \-peers 
97Print a list of the peers.
98This option must not appear in combination with any of the following options:
101Print a list of the peers known to the server as well as a summary
102of their state. This is equivalent to the 'peers' interactive command.
103.It  Fl s , Fl \-showpeers 
104Show a list of the peers.
105This option must not appear in combination with any of the following options:
108Print a list of the peers known to the server as well as a summary
109of their state. This is equivalent to the 'dmpeers' interactive command.
110.It Fl \&? , Fl \-help
111Display usage information and exit.
112.It Fl \&! , Fl \-more\-help
113Pass the extended usage information through a pager.
114.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc
115Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
116configuration file listed in the \fBOPTION PRESETS\fP section, below.
117The command will exit after updating the config file.
118.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts
119Load options from \fIcfgfile\fP.
120The \fIno\-load\-opts\fP form will disable the loading
121of earlier config/rc/ini files.  \fI\-\-no\-load\-opts\fP is handled early,
122out of order.
123.It Fl \-version Op Brq Ar v|c|n
124Output version of program and exit.  The default mode is `v', a simple
125version.  The `c' mode will print copyright information and `n' will
126print the full copyright notice.
129Any option that is not marked as \fInot presettable\fP may be preset
130by loading values from configuration ("RC" or ".INI") file(s) and values from
131environment variables named:
133  \fBNTPDC_<option\-name>\fP or \fBNTPDC\fP
136The environmental presets take precedence (are processed later than)
137the configuration files.
138The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP".
139If any of these are directories, then the file \fI.ntprc\fP
140is searched for within those directories.
141.Sh USAGE
142If one or more request options are included on the command line
145is executed, each of the requests will be sent
146to the NTP servers running on each of the hosts given as command
147line arguments, or on localhost by default.
148If no request options
149are given,
151will attempt to read commands from the
152standard input and execute these on the NTP server running on the
153first host given on the command line, again defaulting to localhost
154when no other host is specified.
157utility will prompt for
158commands if the standard input is a terminal device.
162utility uses NTP mode 7 packets to communicate with the
163NTP server, and hence can be used to query any compatible server on
164the network which permits it.
165Note that since NTP is a UDP protocol
166this communication will be somewhat unreliable, especially over
167large distances in terms of network topology.
170utility makes
171no attempt to retransmit requests, and will time requests out if
172the remote host is not heard from within a suitable timeout
175The operation of
177are specific to the particular
178implementation of the
179.Xr ntpd @NTPD_MS@
180daemon and can be expected to
181work only with this and maybe some previous versions of the daemon.
182Requests from a remote
184utility which affect the
185state of the local server must be authenticated, which requires
186both the remote program and local server share a common key and key
189Note that in contexts where a host name is expected, a
190.Fl 4
191qualifier preceding the host name forces DNS resolution to the IPv4 namespace,
192while a
193.Fl 6
194qualifier forces DNS resolution to the IPv6 namespace.
195Specifying a command line option other than
196.Fl i
198.Fl n
199will cause the specified query (queries) to be sent to
200the indicated host(s) immediately.
204attempt to read interactive format commands from the standard
206.Ss "Interactive Commands"
207Interactive format commands consist of a keyword followed by zero
208to four arguments.
209Only enough characters of the full keyword to
210uniquely identify the command need be typed.
211The output of a
212command is normally sent to the standard output, but optionally the
213output of individual commands may be sent to a file by appending a
214.Ql \&> ,
215followed by a file name, to the command line.
217A number of interactive format commands are executed entirely
218within the
220utility itself and do not result in NTP
221mode 7 requests being sent to a server.
222These are described
224.Bl -tag -width indent
225.It Ic \&? Ar command_keyword
226.It Ic help Ar command_keyword
228.Sq Ic \&?
229will print a list of all the command
230keywords known to this incarnation of
231.Nm .
233.Sq Ic \&?
234followed by a command keyword will print function and usage
235information about the command.
236This command is probably a better
237source of information about
238.Xr ntpq @NTPQ_MS@
239than this manual
241.It Ic delay Ar milliseconds
242Specify a time interval to be added to timestamps included in
243requests which require authentication.
244This is used to enable
245(unreliable) server reconfiguration over long delay network paths
246or between machines whose clocks are unsynchronized.
247Actually the
248server does not now require timestamps in authenticated requests,
249so this command may be obsolete.
250.It Ic host Ar hostname
251Set the host to which future queries will be sent.
252Hostname may
253be either a host name or a numeric address.
254.It Ic hostnames Op Cm yes | Cm no
256.Cm yes
257is specified, host names are printed in
258information displays.
260.Cm no
261is specified, numeric
262addresses are printed instead.
263The default is
264.Cm yes ,
266modified using the command line
267.Fl n
269.It Ic keyid Ar keyid
270This command allows the specification of a key number to be
271used to authenticate configuration requests.
272This must correspond
273to a key number the server has been configured to use for this
275.It Ic quit
277.Nm .
278.It Ic passwd
279This command prompts you to type in a password (which will not
280be echoed) which will be used to authenticate configuration
282The password must correspond to the key configured for
283use by the NTP server for this purpose if such requests are to be
285.It Ic timeout Ar milliseconds
286Specify a timeout period for responses to server queries.
288default is about 8000 milliseconds.
289Note that since
291retries each query once after a timeout, the total waiting time for
292a timeout will be twice the timeout value set.
294.Ss "Control Message Commands"
295Query commands result in NTP mode 7 packets containing requests for
296information being sent to the server.
297These are read\-only commands
298in that they make no modification of the server configuration
300.Bl -tag -width indent
301.It Ic listpeers
302Obtains and prints a brief list of the peers for which the
303server is maintaining state.
304These should include all configured
305peer associations as well as those peers whose stratum is such that
306they are considered by the server to be possible future
307synchronization candidates.
308.It Ic peers
309Obtains a list of peers for which the server is maintaining
310state, along with a summary of that state.
311Summary information
312includes the address of the remote peer, the local interface
313address ( if a local address has yet to be determined), the
314stratum of the remote peer (a stratum of 16 indicates the remote
315peer is unsynchronized), the polling interval, in seconds, the
316reachability register, in octal, and the current estimated delay,
317offset and dispersion of the peer, all in seconds.
319The character in the left margin indicates the mode this peer
320entry is operating in.
322.Ql \&+
323denotes symmetric active, a
324.Ql \&\-
325indicates symmetric passive, a
326.Ql \&=
327means the
328remote server is being polled in client mode, a
329.Ql \&^
330indicates that the server is broadcasting to this address, a
331.Ql \&~
332denotes that the remote peer is sending broadcasts and a
333.Ql \&~
334denotes that the remote peer is sending broadcasts and a
335.Ql \&*
336marks the peer the server is currently synchronizing
339The contents of the host field may be one of four forms.
340It may
341be a host name, an IP address, a reference clock implementation
342name with its parameter or
343.Fn REFCLK "implementation_number" "parameter" .
345.Ic hostnames
346.Cm no
347only IP\-addresses
348will be displayed.
349.It Ic dmpeers
350A slightly different peer summary list.
351Identical to the output
352of the
353.Ic peers
354command, except for the character in the
355leftmost column.
356Characters only appear beside peers which were
357included in the final stage of the clock selection algorithm.
359.Ql \&.
360indicates that this peer was cast off in the falseticker
361detection, while a
362.Ql \&+
363indicates that the peer made it
366.Ql \&*
367denotes the peer the server is currently
368synchronizing with.
369.It Ic showpeer Ar peer_address Oo Ar ... Oc
370Shows a detailed display of the current peer variables for one
371or more peers.
372Most of these values are described in the NTP
373Version 2 specification.
374.It Ic pstats Ar peer_address Oo Ar ... Oc
375Show per\-peer statistic counters associated with the specified
377.It Ic clockstat Ar clock_peer_address Oo Ar ... Oc
378Obtain and print information concerning a peer clock.
380values obtained provide information on the setting of fudge factors
381and other clock performance information.
382.It Ic kerninfo
383Obtain and print kernel phase\-lock loop operating parameters.
384This information is available only if the kernel has been specially
385modified for a precision timekeeping function.
386.It Ic loopinfo Op Cm oneline | Cm multiline
387Print the values of selected loop filter variables.
388The loop
389filter is the part of NTP which deals with adjusting the local
390system clock.
392.Sq offset
393is the last offset given to the
394loop filter by the packet processing code.
396.Sq frequency
397is the frequency error of the local clock in parts\-per\-million
400.Sq time_const
401controls the stiffness of the
402phase\-lock loop and thus the speed at which it can adapt to
403oscillator drift.
405.Sq watchdog timer
406value is the number
407of seconds which have elapsed since the last sample offset was
408given to the loop filter.
410.Cm oneline
412.Cm multiline
413options specify the format in which this
414information is to be printed, with
415.Cm multiline
416as the
418.It Ic sysinfo
419Print a variety of system state variables, i.e., state related
420to the local server.
421All except the last four lines are described
422in the NTP Version 3 specification, RFC\-1305.
425.Sq system flags
426show various system flags, some of
427which can be set and cleared by the
428.Ic enable
430.Ic disable
431configuration commands, respectively.
432These are
434.Cm auth ,
435.Cm bclient ,
436.Cm monitor ,
437.Cm pll ,
438.Cm pps
440.Cm stats
442See the
443.Xr ntpd @NTPD_MS@
444documentation for the meaning of these flags.
446are two additional flags which are read only, the
447.Cm kernel_pll
449.Cm kernel_pps .
450These flags indicate
451the synchronization status when the precision time kernel
452modifications are in use.
454.Sq kernel_pll
455indicates that
456the local clock is being disciplined by the kernel, while the
457.Sq kernel_pps
458indicates the kernel discipline is provided by the PPS
462.Sq stability
463is the residual frequency error remaining
464after the system frequency correction is applied and is intended for
465maintenance and debugging.
466In most architectures, this value will
467initially decrease from as high as 500 ppm to a nominal value in
468the range .01 to 0.1 ppm.
469If it remains high for some time after
470starting the daemon, something may be wrong with the local clock,
471or the value of the kernel variable
472.Va kern.clockrate.tick
473may be
477.Sq broadcastdelay
478shows the default broadcast delay,
479as set by the
480.Ic broadcastdelay
481configuration command.
484.Sq authdelay
485shows the default authentication delay,
486as set by the
487.Ic authdelay
488configuration command.
489.It Ic sysstats
490Print statistics counters maintained in the protocol
492.It Ic memstats
493Print statistics counters related to memory allocation
495.It Ic iostats
496Print statistics counters maintained in the input\-output
498.It Ic timerstats
499Print statistics counters maintained in the timer/event queue
500support code.
501.It Ic reslist
502Obtain and print the server's restriction list.
503This list is
504(usually) printed in sorted order and may help to understand how
505the restrictions are applied.
506.It Ic monlist Op Ar version
507Obtain and print traffic counts collected and maintained by the
508monitor facility.
509The version number should not normally need to be
511.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc
512Obtain debugging information for a reference clock driver.
514information is provided only by some clock drivers and is mostly
515undecodable without a copy of the driver source in hand.
517.Ss "Runtime Configuration Requests"
518All requests which cause state changes in the server are
519authenticated by the server using a configured NTP key (the
520facility can also be disabled by the server by not configuring a
522The key number and the corresponding key must also be made
523known to
524.Nm .
525This can be done using the
526.Ic keyid
528.Ic passwd
529commands, the latter of which will prompt at the terminal for a
530password to use as the encryption key.
531You will also be prompted
532automatically for both the key number and password the first time a
533command which would result in an authenticated request to the
534server is given.
535Authentication not only provides verification that
536the requester has permission to make such changes, but also gives
537an extra degree of protection again transmission errors.
539Authenticated requests always include a timestamp in the packet
540data, which is included in the computation of the authentication
542This timestamp is compared by the server to its receive time
544If they differ by more than a small amount the request is
546This is done for two reasons.
547First, it makes simple
548replay attacks on the server, by someone who might be able to
549overhear traffic on your LAN, much more difficult.
550Second, it makes
551it more difficult to request configuration changes to your server
552from topologically remote hosts.
553While the reconfiguration facility
554will work well with a server on the local host, and may work
555adequately between time\-synchronized hosts on the same LAN, it will
556work very poorly for more distant hosts.
557As such, if reasonable
558passwords are chosen, care is taken in the distribution and
559protection of keys and appropriate source address restrictions are
560applied, the run time reconfiguration facility should provide an
561adequate level of security.
563The following commands all make authenticated requests.
564.Bl -tag -width indent
565.It Xo Ic addpeer Ar peer_address
566.Op Ar keyid
567.Op Ar version
568.Op Cm prefer
570Add a configured peer association at the given address and
571operating in symmetric active mode.
572Note that an existing
573association with the same peer may be deleted when this command is
574executed, or may simply be converted to conform to the new
575configuration, as appropriate.
576If the optional
577.Ar keyid
578is a
579nonzero integer, all outgoing packets to the remote server will
580have an authentication field attached encrypted with this key.
582the value is 0 (or not given) no authentication will be done.
584.Ar version
585can be 1, 2 or 3 and defaults to 3.
587.Cm prefer
588keyword indicates a preferred peer (and thus will
589be used primarily for clock synchronisation if possible).
591preferred peer also determines the validity of the PPS signal \- if
592the preferred peer is suitable for synchronisation so is the PPS
594.It Xo Ic addserver Ar peer_address
595.Op Ar keyid
596.Op Ar version
597.Op Cm prefer
599Identical to the addpeer command, except that the operating
600mode is client.
601.It Xo Ic broadcast Ar peer_address
602.Op Ar keyid
603.Op Ar version
604.Op Cm prefer
606Identical to the addpeer command, except that the operating
607mode is broadcast.
608In this case a valid key identifier and key are
611.Ar peer_address
612parameter can be the broadcast
613address of the local network or a multicast group address assigned
614to NTP.
615If a multicast address, a multicast\-capable kernel is
617.It Ic unconfig Ar peer_address Oo Ar ... Oc
618This command causes the configured bit to be removed from the
619specified peer(s).
620In many cases this will cause the peer
621association to be deleted.
622When appropriate, however, the
623association may persist in an unconfigured mode if the remote peer
624is willing to continue on in this fashion.
625.It Xo Ic fudge Ar peer_address
626.Op Cm time1
627.Op Cm time2
628.Op Ar stratum
629.Op Ar refid
631This command provides a way to set certain data for a reference
633See the source listing for further information.
634.It Xo Ic enable
636.Cm auth | Cm bclient |
637.Cm calibrate | Cm kernel |
638.Cm monitor | Cm ntp |
639.Cm pps | Cm stats
642.It Xo Ic disable
644.Cm auth | Cm bclient |
645.Cm calibrate | Cm kernel |
646.Cm monitor | Cm ntp |
647.Cm pps | Cm stats
650These commands operate in the same way as the
651.Ic enable
653.Ic disable
654configuration file commands of
655.Xr ntpd @NTPD_MS@ .
656.Bl -tag -width indent
657.It Cm auth
658Enables the server to synchronize with unconfigured peers only
659if the peer has been correctly authenticated using either public key
660or private key cryptography.
661The default for this flag is enable.
662.It Cm bclient
663Enables the server to listen for a message from a broadcast or
664multicast server, as in the multicastclient command with
665default address.
666The default for this flag is disable.
667.It Cm calibrate
668Enables the calibrate feature for reference clocks.
669The default for this flag is disable.
670.It Cm kernel
671Enables the kernel time discipline, if available.
672The default for this flag is enable if support is available, otherwise disable.
673.It Cm monitor
674Enables the monitoring facility.
675See the documentation here about the
676.Cm monlist
677command or further information.
678The default for this flag is enable.
679.It Cm ntp
680Enables time and frequency discipline.
681In effect, this switch opens and closes the feedback loop,
682which is useful for testing.
683The default for this flag is enable.
684.It Cm pps
685Enables the pulse\-per\-second (PPS) signal when frequency
686and time is disciplined by the precision time kernel modifications.
687See the
688.Qq A Kernel Model for Precision Timekeeping
689(available as part of the HTML documentation
690provided in
691.Pa /usr/share/doc/ntp )
692page for further information.
693The default for this flag is disable.
694.It Cm stats
695Enables the statistics facility.
696See the
697.Sx Monitoring Options
698section of
699.Xr ntp.conf 5
700for further information.
701The default for this flag is disable.
703.It Xo Ic restrict Ar address Ar mask
704.Ar flag Oo Ar ... Oc
706This command operates in the same way as the
707.Ic restrict
708configuration file commands of
709.Xr ntpd @NTPD_MS@ .
710.It Xo Ic unrestrict Ar address Ar mask
711.Ar flag Oo Ar ... Oc
713Unrestrict the matching entry from the restrict list.
714.It Xo Ic delrestrict Ar address Ar mask
715.Op Cm ntpport
717Delete the matching entry from the restrict list.
718.It Ic readkeys
719Causes the current set of authentication keys to be purged and
720a new set to be obtained by rereading the keys file (which must
721have been specified in the
722.Xr ntpd @NTPD_MS@
723configuration file).
725allows encryption keys to be changed without restarting the
727.It Ic trustedkey Ar keyid Oo Ar ... Oc
728.It Ic untrustedkey Ar keyid Oo Ar ... Oc
729These commands operate in the same way as the
730.Ic trustedkey
732.Ic untrustedkey
733configuration file
734commands of
735.Xr ntpd @NTPD_MS@ .
736.It Ic authinfo
737Returns information concerning the authentication module,
738including known keys and counts of encryptions and decryptions
739which have been done.
740.It Ic traps
741Display the traps set in the server.
742See the source listing for
743further information.
744.It Xo Ic addtrap Ar address
745.Op Ar port
746.Op Ar interface
748Set a trap for asynchronous messages.
749See the source listing
750for further information.
751.It Xo Ic clrtrap Ar address
752.Op Ar port
753.Op Ar interface
755Clear a trap for asynchronous messages.
756See the source listing
757for further information.
758.It Ic reset
759Clear the statistics counters in various modules of the server.
760See the source listing for further information.
763See \fBOPTION PRESETS\fP for configuration environment variables.
764.Sh "FILES"
765See \fBOPTION PRESETS\fP for configuration files.
767One of the following exit values will be returned:
768.Bl -tag
769.It 0 " (EXIT_SUCCESS)"
770Successful program execution.
771.It 1 " (EXIT_FAILURE)"
772The operation failed or the command syntax was not valid.
773.It 66 " (EX_NOINPUT)"
774A specified configuration file could not be loaded.
775.It 70 " (EX_SOFTWARE)"
776libopts had an internal operational error.  Please report
777it to autogen\-users@lists.sourceforge.net.  Thank you.
779.Sh "SEE ALSO"
780.Xr ntp.conf 5 ,
781.Xr ntpd @NTPD_MS@
783.%A David L. Mills
784.%T Network Time Protocol (Version 3)
785.%O RFC1305
788The formatting directives in this document came from FreeBSD.
790Copyright (C) 1992\-2020 The University of Delaware and Network Time Foundation all rights reserved.
791This program is released under the terms of the NTP license, <http://ntp.org/license>.
792.Sh BUGS
795utility is a crude hack.
796Much of the information it shows is
797deadly boring and could only be loved by its implementer.
799program was designed so that new (and temporary) features were easy
800to hack in, at great expense to the program's ease of use.
802this, the program is occasionally useful.
804Please report bugs to http://bugs.ntp.org .
806Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
807.Sh "NOTES"
808This manual page was \fIAutoGen\fP\-erated from the \fBntpdc\fP
809option definitions.