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