"Fossies" - the Fresh Open Source Software Archive

Member "ntp-4.2.8p15/ntpq/ntpq.mdoc.in" (23 Jun 2020, 32391 Bytes) of package /linux/misc/ntp-4.2.8p15.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "ntpq.mdoc.in": 4.2.8p14_vs_4.2.8p15.

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