1/* -*- Mode: Text -*- */
2
3autogen definitions options;
4
5#include copyright.def
6#include homerc.def
7#include autogen-version.def
8
9prog-name      = "ntpq";
10prog-title     = "standard NTP query program";
11argument       = '[ host ...]';
12
13flag = {
14    name      = ipv4;
15    flags-cant = ipv6;
16    value     = 4;
17    descrip   = "Force IPv4 name resolution";
18    doc = <<-  _EndOfDoc_
19	Force resolution of following host names on the command line
20	to the IPv4 namespace.
21	_EndOfDoc_;
22};
23
24flag = {
25    name      = ipv6;
26    flags-cant = ipv4;
27    value     = 6;
28    descrip   = "Force IPv6 name resolution";
29    doc = <<-  _EndOfDoc_
30	Force resolution of following host names on the command line
31	to the IPv6 namespace.
32	_EndOfDoc_;
33};
34
35flag = {
36    name      = command;
37    value     = c;
38    arg-type  = string;
39    descrip   = "run a command and exit";
40    max       = NOLIMIT;
41    arg-name  = cmd;
42    call-proc = ntpq_custom_opt_handler;
43    doc = <<-  _EndOfDoc_
44	The following argument is interpreted as an interactive format command
45	and is added to the list of commands to be executed on the specified
46	host(s).
47	_EndOfDoc_;
48};
49
50#include debug-opt.def
51
52flag = {
53    name      = interactive;
54    value     = i;
55    flags-cant = command, peers;
56    descrip   = "Force ntpq to operate in interactive mode";
57    doc = <<-  _EndOfDoc_
58	Force @code{ntpq} to operate in interactive mode.
59	Prompts will be written to the standard output and
60	commands read from the standard input.
61	_EndOfDoc_;
62};
63
64flag = {
65    name      = numeric;
66    value     = n;
67    descrip   = "numeric host addresses";
68    doc = <<-  _EndOfDoc_
69	Output all host addresses in dotted-quad numeric format rather than
70	converting to the canonical host names.
71	_EndOfDoc_;
72};
73
74flag = {
75    name      = old-rv;
76    descrip   = "Always output status line with readvar";
77    doc = <<-  _EndOfDoc_
78	By default, @code{ntpq} now suppresses the @code{associd=...}
79	line that precedes the output of @code{readvar}
80	(alias @code{rv}) when a single variable is requested, such as
81	@code{ntpq -c "rv 0 offset"}.
82	This option causes @code{ntpq} to include both lines of output
83	for a single-variable @code{readvar}.
84	Using an environment variable to
85	preset this option in a script will enable both older and
86	newer @code{ntpq} to behave identically in this regard.
87	_EndOfDoc_;
88};
89
90flag = {
91    name      = peers;
92    value     = p;
93    descrip   = "Print a list of the peers";
94    flags-cant = interactive;
95    call-proc = ntpq_custom_opt_handler;
96    doc = <<-  _EndOfDoc_
97	Print a list of the peers known to the server as well as a summary
98	of their state. This is equivalent to the 'peers' interactive command.
99	_EndOfDoc_;
100};
101
102flag = {
103    name      = refid;
104    value     = r;
105    descrip   = "Set default display type for S2+ refids";
106    arg-type  = keyword;
107    keyword   = hash, ipv4;
108    arg-default = ipv4;
109    doc = <<-  _EndOfDoc_
110	Set the default display format for S2+ refids.
111	_EndOfDoc_;
112};
113
114flag = {
115    name      = wide;
116    value     = w;
117    descrip   = "Display the full 'remote' value";
118    doc = <<-  _EndOfDoc_
119	Display the full value of the 'remote' value.  If this requires
120	more than 15 characters, display the full value, emit a newline,
121	and continue the data display properly indented on the next line.
122	_EndOfDoc_;
123};
124
125doc-section	= {
126  ds-type	= 'DESCRIPTION';
127  ds-format	= 'mdoc';
128  ds-text	= <<-  _END_PROG_MDOC_DESCRIP
129.Pp
130The
131.Nm
132utility program is used to query NTP servers to monitor NTP operations
133and performance, requesting
134information about current state and/or changes in that state.
135The program may be run either in interactive mode or controlled using
136command line arguments.
137Requests to read and write arbitrary
138variables can be assembled, with raw and pretty-printed output
139options being available.
140The
141.Nm
142utility can also obtain and print a
143list of peers in a common format by sending multiple queries to the
144server.
145.Pp
146If one or more request options is included on the command line
147when
148.Nm
149is executed, each of the requests will be sent
150to the NTP servers running on each of the hosts given as command
151line arguments, or on localhost by default.
152If no request options
153are given,
154.Nm
155will attempt to read commands from the
156standard input and execute these on the NTP server running on the
157first host given on the command line, again defaulting to localhost
158when no other host is specified.
159The
160.Nm
161utility will prompt for
162commands if the standard input is a terminal device.
163.Pp
164.Nm
165uses NTP mode 6 packets to communicate with the
166NTP server, and hence can be used to query any compatible server on
167the network which permits it.
168Note that since NTP is a UDP protocol
169this communication will be somewhat unreliable, especially over
170large distances in terms of network topology.
171The
172.Nm
173utility makes
174one attempt to retransmit requests, and will time requests out if
175the remote host is not heard from within a suitable timeout
176time.
177.Pp
178Note that in contexts where a host name is expected, a
179.Fl 4
180qualifier preceding the host name forces resolution to the IPv4
181namespace, while a
182.Fl 6
183qualifier forces resolution to the IPv6 namespace.
184For examples and usage, see the
185.Dq NTP Debugging Techniques
186page.
187.Pp
188Specifying a
189command line option other than
190.Fl i
191or
192.Fl n
193will
194cause the specified query (queries) to be sent to the indicated
195host(s) immediately.
196Otherwise,
197.Nm
198will attempt to read
199interactive format commands from the standard input.
200
201.Ss "Internal Commands"
202.Pp
203Interactive format commands consist of a keyword followed by zero
204to four arguments.
205Only enough characters of the full keyword to
206uniquely identify the command need be typed.
207.Pp
208A
209number of interactive format commands are executed entirely within
210the
211.Nm
212utility itself and do not result in NTP
213requests being sent to a server.
214These are described following.
215.Bl -tag -width "help [command]" -compact -offset indent
216.It Ic ? Op Ar command
217.It Ic help Op Ar command
218A
219.Ql \&?
220by itself will print a list of all the commands
221known to
222.Nm .
223A
224.Ql \&?
225followed by a command name will print function and usage
226information about the command.
227.It Ic addvars Ar name Ns Oo \&= Ns Ar value Oc Ns Op ,...
228.It Ic rmvars Ar name Ns Op ,...
229.It Ic clearvars
230.It Ic showvars
231The arguments to this command consist of a list of
232items of the form
233.Ar name Ns Op \&= Ns Ar value ,
234where the
235.No \&= Ns Ar value
236is ignored, and can be omitted,
237in requests to the server to read variables.
238The
239.Nm
240utility maintains an internal list in which data to be included in
241messages can be assembled, and displayed or set using the
242.Ic readlist
243and
244.Ic writelist
245commands described below.
246The
247.Ic addvars
248command allows variables and their optional values to be added to
249the list.
250If more than one variable is to be added, the list should
251be comma-separated and not contain white space.
252The
253.Ic rmvars
254command can be used to remove individual variables from the list,
255while the
256.Ic clearvars
257command removes all variables from the
258list.
259The
260.Ic showvars
261command displays the current list of optional variables.
262.It Ic authenticate Op Cm yes Ns | Ns Cm no
263Normally
264.Nm
265does not authenticate requests unless
266they are write requests.
267The command
268.Ic authenticate Cm yes
269causes
270.Nm
271to send authentication with all requests it
272makes.
273Authenticated requests causes some servers to handle
274requests slightly differently.
275The command
276.Ic authenticate
277causes
278.Nm
279to display whether or not
280it is currently authenticating requests.
281.It Ic cooked
282Causes output from query commands to be "cooked", so that
283variables which are recognized by
284.Nm
285will have their
286values reformatted for human consumption.
287Variables which
288.Nm
289could not decode completely are
290marked with a trailing
291.Ql \&? .
292.It Ic debug Op Cm more Ns | Ns Cm less Ns | Ns Cm off
293With no argument, displays the current debug level.
294Otherwise, the debugging level is changed as indicated.
295.It Ic delay Op Ar milliseconds
296Specify a time interval to be added to timestamps included in
297requests which require authentication.
298This is used to enable
299(unreliable) server reconfiguration over long delay network paths
300or between machines whose clocks are unsynchronized.
301Actually the
302server does not now require timestamps in authenticated requests,
303so this command may be obsolete.
304Without any arguments, displays the current delay.
305.It Ic drefid Op Cm hash Ns | Ns Cm ipv4
306Display refids as IPv4 or hash.
307Without any arguments, displays whether refids are shown as IPv4
308addresses or hashes.
309.It Ic exit
310Exit
311.Nm .
312.It Ic host Op Ar name
313Set the host to which future queries will be sent.
314The
315.Ar name
316may be either a host name or a numeric address.
317Without any arguments, displays the current host.
318.It Ic hostnames Op Cm yes Ns | Ns Cm no
319If
320.Cm yes
321is specified, host names are printed in
322information displays.
323If
324.Cm no
325is specified, numeric
326addresses are printed instead.
327The default is
328.Cm yes ,
329unless
330modified using the command line
331.Fl n
332switch.
333Without any arguments, displays whether host names or numeric addresses
334are shown.
335.It Ic keyid Op Ar keyid
336This command allows the specification of a key number to be
337used to authenticate configuration requests.
338This must correspond
339to the
340.Cm controlkey
341key number the server has been configured to use for this
342purpose.
343Without any arguments, displays the current
344.Ar keyid .
345.It Ic keytype Op Ar digest
346Specify the digest algorithm to use for authenticating requests, with default
347.Cm MD5 .
348If
349.Nm
350was built with OpenSSL support, and OpenSSL is installed,
351.Ar digest
352can be any message digest algorithm supported by OpenSSL.
353If no argument is given, the current
354.Ic keytype Ar digest
355algorithm used is displayed.
356.It Ic ntpversion Op Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3 Ns | Ns Cm 4
357Sets the NTP version number which
358.Nm
359claims in
360packets.
361Defaults to 3, and note that mode 6 control messages (and
362modes, for that matter) didn't exist in NTP version 1.
363There appear
364to be no servers left which demand version 1.
365With no argument, displays the current NTP version that will be used
366when communicating with servers.
367.It Ic passwd
368This command prompts you to type in a password (which will not
369be echoed) which will be used to authenticate configuration
370requests.
371The password must correspond to the key configured for
372use by the NTP server for this purpose if such requests are to be
373successful.
374.It Ic poll Oo Ar n Oc Op Cm verbose
375Poll an NTP server in client mode
376.Ar n
377times.
378Poll not implemented yet.
379.It Ic quit
380Exit
381.Nm .
382.It Ic raw
383Causes all output from query commands is printed as received
384from the remote server.
385The only formating/interpretation done on
386the data is to transform nonascii data into a printable (but barely
387understandable) form.
388.It Ic timeout Op Ar milliseconds
389Specify a timeout period for responses to server queries.
390The
391default is about 5000 milliseconds.
392Without any arguments, displays the current timeout period.
393Note that since
394.Nm
395retries each query once after a timeout, the total waiting time for
396a timeout will be twice the timeout value set.
397.It Ic version
398Display the version of the
399.Nm
400program.
401.El
402
403.Ss "Control Message Commands"
404Association ids are used to identify system, peer and clock variables.
405System variables are assigned an association id of zero and system name
406space, while each association is assigned a nonzero association id and
407peer namespace.
408Most control commands send a single message to the server and expect a
409single response message.
410The exceptions are the
411.Ic peers
412command, which sends a series of messages,
413and the
414.Ic mreadlist
415and
416.Ic mreadvar
417commands, which iterate over a range of associations.
418.Bl -tag -width "something" -compact -offset indent
419.It Ic apeers
420Display a list of peers in the form:
421.Dl [tally]remote refid assid st t when pool reach delay offset jitter
422where the output is just like the
423.Ic peers
424command except that the
425.Cm refid
426is displayed in hex format and the association number is also displayed.
427.It Ic associations
428Display a list of mobilized associations in the form:
429.Dl ind assid status conf reach auth condition last_event cnt
430.Bl -column -offset indent ".Sy Variable" "see the select field of the peer status word"
431.It Sy Variable Ta Sy Description
432.It Cm ind Ta index on this list
433.It Cm assid Ta association id
434.It Cm status Ta peer status word
435.It Cm conf Ta Cm yes : No persistent, Cm no : No ephemeral
436.It Cm reach Ta Cm yes : No reachable, Cm no : No unreachable
437.It Cm auth Ta Cm ok , Cm yes , Cm bad No and Cm none
438.It Cm condition Ta selection status \&(see the Cm select No field of the peer status word\&)
439.It Cm last_event Ta event report \&(see the Cm event No field of the peer status word\&)
440.It Cm cnt Ta event count \&(see the Cm count No field of the peer status word\&)
441.El
442.It Ic authinfo
443Display the authentication statistics counters:
444time since reset, stored keys, free keys, key lookups, keys not found,
445uncached keys, expired keys, encryptions, decryptions.
446.It Ic clocklist Op Ar associd
447.It Ic cl Op Ar associd
448Display all clock variables in the variable list for those associations
449supporting a reference clock.
450.It Ic clockvar Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,...
451.It Ic cv Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,...
452Display a list of clock variables for those associations supporting a
453reference clock.
454.It Ic :config Ar "configuration command line"
455Send the remainder of the command line, including whitespace, to the
456server as a run-time configuration command in the same format as a line
457in the configuration file.
458This command is experimental until further notice and clarification.
459Authentication is of course required.
460.It Ic config-from-file Ar filename
461Send each line of
462.Ar filename
463to the server as run-time configuration commands in the same format as
464lines in the configuration file.
465This command is experimental until further notice and clarification.
466Authentication is required.
467.It Ic ifstats
468Display status and statistics counters for each local network interface address:
469interface number, interface name and address or broadcast, drop, flag,
470ttl, mc, received, sent, send failed, peers, uptime.
471Authentication is required.
472.It Ic iostats
473Display network and reference clock I/O statistics:
474time since reset, receive buffers, free receive buffers, used receive buffers,
475low water refills, dropped packets, ignored packets, received packets,
476packets sent, packet send failures, input wakeups, useful input wakeups.
477.It Ic kerninfo
478Display kernel loop and PPS statistics:
479associd, status, pll offset, pll frequency, maximum error,
480estimated error, kernel status, pll time constant, precision,
481frequency tolerance, pps frequency, pps stability, pps jitter,
482calibration interval, calibration cycles, jitter exceeded,
483stability exceeded, calibration errors.
484As with other ntpq output, times are in milliseconds; very small values
485may be shown as exponentials.
486The precision value displayed is in milliseconds as well, unlike the
487precision system variable.
488.It Ic lassociations
489Perform the same function as the associations command, except display
490mobilized and unmobilized associations, including all clients.
491.It Ic lopeers Op Fl 4 Ns | Ns Fl 6
492Display a list of all peers and clients showing
493.Cm dstadr
494(associated with the given IP version).
495.It Ic lpassociations
496Display the last obtained list of associations, including all clients.
497.It Ic lpeers Op Fl 4 Ns | Ns Fl 6
498Display a list of all peers and clients (associated with the given IP version).
499.It Ic monstats
500Display monitor facility status, statistics, and limits:
501enabled, addresses, peak addresses, maximum addresses,
502reclaim above count, reclaim older than, kilobytes, maximum kilobytes.
503.It Ic mreadlist Ar associdlo Ar associdhi
504.It Ic mrl Ar associdlo Ar associdhi
505Perform the same function as the
506.Ic readlist
507command for a range of association ids.
508.It Ic mreadvar Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,...
509This range may be determined from the list displayed by any
510command showing associations.
511.It Ic mrv Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,...
512Perform the same function as the
513.Ic readvar
514command for a range of association ids.
515This range may be determined from the list displayed by any
516command showing associations.
517.It Xo Ic mrulist Oo Cm limited | Cm kod | Cm mincount Ns \&= Ns Ar count |
518.Cm laddr Ns \&= Ns Ar localaddr | Cm sort Ns \&= Ns Oo \&- Oc Ns Ar sortorder |
519.Cm resany Ns \&= Ns Ar hexmask | Cm resall Ns \&= Ns Ar hexmask Oc
520.Xc
521Display traffic counts of the most recently seen source addresses
522collected and maintained by the monitor facility.
523With the exception of
524.Cm sort Ns \&= Ns Oo \&- Oc Ns Ar sortorder ,
525the options filter the list returned by
526.Xr ntpd 8 .
527The
528.Cm limited
529and
530.Cm kod
531options return only entries representing client addresses from which the
532last packet received triggered either discarding or a KoD response.
533The
534.Cm mincount Ns = Ns Ar count
535option filters entries representing less than
536.Ar count
537packets.
538The
539.Cm laddr Ns = Ns Ar localaddr
540option filters entries for packets received on any local address other than
541.Ar localaddr .
542.Cm resany Ns = Ns Ar hexmask
543and
544.Cm resall Ns = Ns Ar hexmask
545filter entries containing none or less than all, respectively, of the bits in
546.Ar hexmask ,
547which must begin with
548.Cm 0x .
549The
550.Ar sortorder
551defaults to
552.Cm lstint
553and may be
554.Cm addr ,
555.Cm avgint ,
556.Cm count ,
557.Cm lstint ,
558or any of those preceded by
559.Ql \&-
560to reverse the sort order.
561The output columns are:
562.Bl -tag -width "something" -compact -offset indent
563.It Column
564Description
565.It Ic lstint
566Interval in seconds between the receipt of the most recent packet from
567this address and the completion of the retrieval of the MRU list by
568.Nm .
569.It Ic avgint
570Average interval in s between packets from this address.
571.It Ic rstr
572Restriction flags associated with this address.
573Most are copied unchanged from the matching
574.Ic restrict
575command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless
576the last packet from this address triggered a rate control response.
577.It Ic r
578Rate control indicator, either
579a period,
580.Ic L
581or
582.Ic K
583for no rate control response,
584rate limiting by discarding, or rate limiting with a KoD response, respectively.
585.It Ic m
586Packet mode.
587.It Ic v
588Packet version number.
589.It Ic count
590Packets received from this address.
591.It Ic rport
592Source port of last packet from this address.
593.It Ic remote address
594host or DNS name, numeric address, or address followed by
595claimed DNS name which could not be verified in parentheses.
596.El
597.It Ic opeers Op Fl 4 | Fl 6
598Obtain and print the old-style list of all peers and clients showing
599.Cm dstadr
600(associated with the given IP version),
601rather than the
602.Cm refid .
603.It Ic passociations
604Perform the same function as the
605.Ic associations
606command,
607except that it uses previously stored data rather than making a new query.
608.It Ic peers
609Display a list of peers in the form:
610.Dl [tally]remote refid st t when pool reach delay offset jitter
611.Bl -tag -width "something" -compact -offset indent
612.It Variable
613Description
614.It Cm [tally]
615single-character code indicating current value of the
616.Ic select
617field of the
618.Lk decode.html#peer "peer status word"
619.It Cm remote
620host name (or IP number) of peer.
621The value displayed will be truncated to 15 characters unless the
622.Nm
623.Fl w
624option is given, in which case the full value will be displayed
625on the first line, and if too long,
626the remaining data will be displayed on the next line.
627.It Cm refid
628source IP address or
629.Lk decode.html#kiss "'kiss code"
630.It Cm st
631stratum: 0 for local reference clocks, 1 for servers with local
632reference clocks, ..., 16 for unsynchronized server clocks
633.It Cm t
634.Ic u :
635unicast or manycast client,
636.Ic b :
637broadcast or multicast client,
638.Ic p :
639pool source,
640.Ic l :
641local (reference clock),
642.Ic s :
643symmetric (peer),
644.Ic A :
645manycast server,
646.Ic B :
647broadcast server,
648.Ic M :
649multicast server
650.It Cm when
651time in seconds, minutes, hours, or days since the last packet
652was received, or
653.Ql \&-
654if a packet has never been received
655.It Cm poll
656poll interval (s)
657.It Cm reach
658reach shift register (octal)
659.It Cm delay
660roundtrip delay
661.It Cm offset
662offset of server relative to this host
663.It Cm jitter
664offset RMS error estimate.
665.El
666.It Ic pstats Ar associd
667Display the statistics for the peer with the given
668.Ar associd :
669associd, status, remote host, local address, time last received,
670time until next send, reachability change, packets sent,
671packets received, bad authentication, bogus origin, duplicate,
672bad dispersion, bad reference time, candidate order.
673.It Ic readlist Op Ar associd
674.It Ic rl Op Ar associd
675Display all system or peer variables.
676If the
677.Ar associd
678is omitted, it is assumed to be zero.
679.It Ic readvar Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ...
680.It Ic rv Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ...
681Display the specified system or peer variables.
682If
683.Ar associd
684is zero, the variables are from the
685.Sx System Variables
686name space, otherwise they are from the
687.Sx Peer Variables
688name space.
689The
690.Ar associd
691is required, as the same name can occur in both spaces.
692If no
693.Ar name
694is included, all operative variables in the name space are displayed.
695In this case only, if the
696.Ar associd
697is omitted, it is assumed to be zero.
698Multiple names are specified with comma separators and without whitespace.
699Note that time values are represented in milliseconds
700and frequency values in parts-per-million (PPM).
701Some NTP timestamps are represented in the format
702.Ar YYYY Ns Ar MM Ar DD Ar TTTT ,
703where
704.Ar YYYY
705is the year,
706.Ar MM
707the month of year,
708.Ar DD
709the day of month and
710.Ar TTTT
711the time of day.
712.It Ic reslist
713Display the access control (restrict) list for
714.Nm .
715Authentication is required.
716.It Ic saveconfig Ar filename
717Save the current configuration,
718including any runtime modifications made by
719.Ic :config
720or
721.Ic config-from-file ,
722to the NTP server host file
723.Ar filename .
724This command will be rejected by the server unless
725.Lk miscopt.html#saveconfigdir "saveconfigdir"
726appears in the
727.Xr ntpd 8
728configuration file.
729.Ar filename
730can use
731.Xr date 1
732format specifiers to substitute the current date and time, for
733example,
734.D1 Ic saveconfig Pa ntp-%Y%m%d-%H%M%S.conf .
735The filename used is stored in system variable
736.Cm savedconfig .
737Authentication is required.
738.It Ic sysinfo
739Display system operational summary:
740associd, status, system peer, system peer mode, leap indicator,
741stratum, log2 precision, root delay, root dispersion,
742reference id, reference time, system jitter, clock jitter,
743clock wander, broadcast delay, symm. auth. delay.
744.It Ic sysstats
745Display system uptime and packet counts maintained in the
746protocol module:
747uptime, sysstats reset, packets received, current version,
748older version, bad length or format, authentication failed,
749declined, restricted, rate limited, KoD responses,
750processed for time.
751.It Ic timerstats
752Display interval timer counters:
753time since reset, timer overruns, calls to transmit.
754.It Ic writelist Ar associd
755Set all system or peer variables included in the variable list.
756.It Ic writevar Ar associd Ar name Ns = Ns Ar value Op , ...
757Set the specified variables in the variable list.
758If the
759.Ar associd
760is zero, the variables are from the
761.Sx System Variables
762name space, otherwise they are from the
763.Sx Peer Variables
764name space.
765The
766.Ar associd
767is required, as the same name can occur in both spaces.
768Authentication is required.
769.El
770
771.Ss Status Words and Kiss Codes
772The current state of the operating program is shown
773in a set of status words
774maintained by the system.
775Status information is also available on a per-association basis.
776These words are displayed by the
777.Ic readlist
778and
779.Ic associations
780commands both in hexadecimal and in decoded short tip strings.
781The codes, tips and short explanations are documented on the
782.Lk decode.html "Event Messages and Status Words"
783page.
784The page also includes a list of system and peer messages,
785the code for the latest of which is included in the status word.
786.Pp
787Information resulting from protocol machine state transitions
788is displayed using an informal set of ASCII strings called
789.Lk decode.html#kiss "kiss codes" .
790The original purpose was for kiss-o'-death (KoD) packets
791sent by the server to advise the client of an unusual condition.
792They are now displayed, when appropriate,
793in the reference identifier field in various billboards.
794
795.Ss System Variables
796The following system variables appear in the
797.Ic readlist
798billboard.
799Not all variables are displayed in some configurations.
800.Pp
801.Bl -tag -width "something" -compact -offset indent
802.It Variable
803Description
804.It Cm status
805.Lk decode.html#sys "system status word"
806.It Cm version
807NTP software version and build time
808.It Cm processor
809hardware platform and version
810.It Cm system
811operating system and version
812.It Cm leap
813leap warning indicator (0-3)
814.It Cm stratum
815stratum (1-15)
816.It Cm precision
817precision (log2 s)
818.It Cm rootdelay
819total roundtrip delay to the primary reference clock
820.It Cm rootdisp
821total dispersion to the primary reference clock
822.It Cm refid
823reference id or
824.Lk decode.html#kiss "kiss code"
825.It Cm reftime
826reference time
827.It Ic clock
828date and time of day
829.It Cm peer
830system peer association id
831.It Cm tc
832time constant and poll exponent (log2 s) (3-17)
833.It Cm mintc
834minimum time constant (log2 s) (3-10)
835.It Cm offset
836combined offset of server relative to this host
837.It Cm frequency
838frequency drift (PPM) relative to hardware clock
839.It Cm sys_jitter
840combined system jitter
841.It Cm clk_wander
842clock frequency wander (PPM)
843.It Cm clk_jitter
844clock jitter
845.It Cm tai
846TAI-UTC offset (s)
847.It Cm leapsec
848NTP seconds when the next leap second is/was inserted
849.It Cm expire
850NTP seconds when the NIST leapseconds file expires
851.El
852The jitter and wander statistics are exponentially-weighted RMS averages.
853The system jitter is defined in the NTPv4 specification;
854the clock jitter statistic is computed by the clock discipline module.
855.Pp
856When the NTPv4 daemon is compiled with the OpenSSL software library,
857additional system variables are displayed,
858including some or all of the following,
859depending on the particular Autokey dance:
860.Bl -tag -width "something" -compact -offset indent
861.It Variable
862Description
863.It Cm host
864Autokey host name for this host
865.It Cm ident
866Autokey group name for this host
867.It Cm flags
868host flags  (see Autokey specification)
869.It Cm digest
870OpenSSL message digest algorithm
871.It Cm signature
872OpenSSL digest/signature scheme
873.It Cm update
874NTP seconds at last signature update
875.It Cm cert
876certificate subject, issuer and certificate flags
877.It Cm until
878NTP seconds when the certificate expires
879.El
880.Ss Peer Variables
881The following peer variables appear in the
882.Ic readlist
883billboard for each association.
884Not all variables are displayed in some configurations.
885.Pp
886.Bl -tag -width "something" -compact -offset indent
887.It Variable
888Description
889.It Cm associd
890association id
891.It Cm status
892.Lk decode.html#peer "peer status word"
893.It Cm srcadr
894source (remote) IP address
895.It Cm srcport
896source (remote) port
897.It Cm dstadr
898destination (local) IP address
899.It Cm dstport
900destination (local) port
901.It Cm leap
902leap indicator (0-3)
903.It Cm stratum
904stratum (0-15)
905.It Cm precision
906precision (log2 s)
907.It Cm rootdelay
908total roundtrip delay to the primary reference clock
909.It Cm rootdisp
910total root dispersion to the primary reference clock
911.It Cm refid
912reference id or
913.Lk decode.html#kiss "kiss code"
914.It Cm reftime
915reference time
916.It Cm rec
917last packet received time
918.It Cm reach
919reach register (octal)
920.It Cm unreach
921unreach counter
922.It Cm hmode
923host mode (1-6)
924.It Cm pmode
925peer mode (1-5)
926.It Cm hpoll
927host poll exponent (log2 s) (3-17)
928.It Cm ppoll
929peer poll exponent (log2 s) (3-17)
930.It Cm headway
931headway (see
932.Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
933.It Cm flash
934.Lk decode.html#flash "flash status word"
935.It Cm keyid
936symmetric key id
937.It Cm offset
938filter offset
939.It Cm delay
940filter delay
941.It Cm dispersion
942filter dispersion
943.It Cm jitter
944filter jitter
945.It Cm bias
946unicast/broadcast bias
947.It Cm xleave
948interleave delay (see
949.Lk xleave.html "NTP Interleaved Modes" )
950.El
951The
952.Cm bias
953variable is calculated when the first broadcast packet is received
954after the calibration volley.
955It represents the offset of the broadcast subgraph relative to the
956unicast subgraph.
957The
958.Cm xleave
959variable appears only for the interleaved symmetric and interleaved modes.
960It represents the internal queuing, buffering and transmission delays
961for the preceding packet.
962.Pp
963When the NTPv4 daemon is compiled with the OpenSSL software library,
964additional peer variables are displayed, including the following:
965.Bl -tag -width "something" -compact -offset indent
966.It Variable
967Description
968.It Cm flags
969peer flags (see Autokey specification)
970.It Cm host
971Autokey server name
972.It Cm flags
973peer flags (see Autokey specification)
974.It Cm signature
975OpenSSL digest/signature scheme
976.It Cm initsequence
977initial key id
978.It Cm initkey
979initial key index
980.It Cm timestamp
981Autokey signature timestamp
982.It Cm ident
983Autokey group name for this association
984.El
985
986.Ss Clock Variables
987The following clock variables appear in the
988.Ic clocklist
989billboard for each association with a reference clock.
990Not all variables are displayed in some configurations.
991.Bl -tag -width "something" -compact -offset indent
992.It Variable
993Description
994.It Cm associd
995association id
996.It Cm status
997.Lk decode.html#clock "clock status word"
998.It Cm device
999device description
1000.It Cm timecode
1001ASCII time code string (specific to device)
1002.It Cm poll
1003poll messages sent
1004.It Cm noreply
1005no reply
1006.It Cm badformat
1007bad format
1008.It Cm baddata
1009bad date or time
1010.It Cm fudgetime1
1011fudge time 1
1012.It Cm fudgetime2
1013fudge time 2
1014.It Cm stratum
1015driver stratum
1016.It Cm refid
1017driver reference id
1018.It Cm flags
1019driver flags
1020.El
1021	_END_PROG_MDOC_DESCRIP;
1022};
1023