119370Spst.Dd June 23 2020 219370Spst.Dt NTPQ @NTPQ_MS@ User Commands 319370Spst.Os 419370Spst.\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc) 519370Spst.\" 619370Spst.\" It has been AutoGen-ed June 23, 2020 at 02:20:53 AM by AutoGen 5.18.5 719370Spst.\" From the definitions ntpq-opts.def 819370Spst.\" and the template file agmdoc-cmd.tpl 919370Spst.Sh NAME 1019370Spst.Nm ntpq 1119370Spst.Nd standard NTP query program 1219370Spst.Sh SYNOPSIS 1319370Spst.Nm 1419370Spst.\" Mixture of short (flag) options and long options 1519370Spst.Op Fl flags 1619370Spst.Op Fl flag Op Ar value 1719370Spst.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc 1819370Spst[ host ...] 1919370Spst.Pp 2019370Spst.Sh DESCRIPTION 2119370Spst.Pp 2219370SpstThe 2319370Spst.Nm 2419370Spstutility program is used to query NTP servers to monitor NTP operations 2519370Spstand performance, requesting 2619370Spstinformation about current state and/or changes in that state. 2719370SpstThe program may be run either in interactive mode or controlled using 2819370Spstcommand line arguments. 2919370SpstRequests to read and write arbitrary 3019370Spstvariables can be assembled, with raw and pretty\-printed output 3119370Spstoptions being available. 3219370SpstThe 3319370Spst.Nm 3419370Spstutility can also obtain and print a 3519370Spstlist of peers in a common format by sending multiple queries to the 3619370Spstserver. 3719370Spst.Pp 3819370SpstIf one or more request options is included on the command line 3919370Spstwhen 4019370Spst.Nm 4119370Spstis executed, each of the requests will be sent 4219370Spstto the NTP servers running on each of the hosts given as command 4319370Spstline arguments, or on localhost by default. 4419370SpstIf no request options 4519370Spstare given, 4619370Spst.Nm 4719370Spstwill attempt to read commands from the 4819370Spststandard input and execute these on the NTP server running on the 4919370Spstfirst host given on the command line, again defaulting to localhost 5019370Spstwhen no other host is specified. 5119370SpstThe 5219370Spst.Nm 5319370Spstutility will prompt for 5419370Spstcommands if the standard input is a terminal device. 5519370Spst.Pp 5619370Spst.Nm 5719370Spstuses NTP mode 6 packets to communicate with the 5819370SpstNTP server, and hence can be used to query any compatible server on 5919370Spstthe network which permits it. 6019370SpstNote that since NTP is a UDP protocol 6119370Spstthis communication will be somewhat unreliable, especially over 6219370Spstlarge distances in terms of network topology. 6319370SpstThe 6419370Spst.Nm 6519370Spstutility makes 6619370Spstone attempt to retransmit requests, and will time requests out if 6719370Spstthe remote host is not heard from within a suitable timeout 6819370Spsttime. 6919370Spst.Pp 7019370SpstNote that in contexts where a host name is expected, a 7119370Spst.Fl 4 7219370Spstqualifier preceding the host name forces resolution to the IPv4 7319370Spstnamespace, while a 7419370Spst.Fl 6 7519370Spstqualifier forces resolution to the IPv6 namespace. 7619370SpstFor examples and usage, see the 7719370Spst.Dq NTP Debugging Techniques 7819370Spstpage. 7919370Spst.Pp 8019370SpstSpecifying a 8119370Spstcommand line option other than 8219370Spst.Fl i 8319370Spstor 8419370Spst.Fl n 8519370Spstwill 8619370Spstcause the specified query (queries) to be sent to the indicated 8719370Spsthost(s) immediately. 8819370SpstOtherwise, 8919370Spst.Nm 9019370Spstwill attempt to read 9119370Spstinteractive format commands from the standard input. 9219370Spst.Ss "Internal Commands" 9319370Spst.Pp 9419370SpstInteractive format commands consist of a keyword followed by zero 9519370Spstto four arguments. 9619370SpstOnly enough characters of the full keyword to 9719370Spstuniquely identify the command need be typed. 9819370Spst.Pp 9919370SpstA 10019370Spstnumber of interactive format commands are executed entirely within 10119370Spstthe 10219370Spst.Nm 10319370Spstutility itself and do not result in NTP 10419370Spstrequests being sent to a server. 10519370SpstThese are described following. 10619370Spst.Bl -tag -width "help [command]" -compact -offset indent 10719370Spst.It Ic ? Op Ar command 10819370Spst.It Ic help Op Ar command 10919370SpstA 11019370Spst.Ql \&? 11119370Spstby itself will print a list of all the commands 11219370Spstknown to 11319370Spst.Nm . 11419370SpstA 11519370Spst.Ql \&? 11619370Spstfollowed by a command name will print function and usage 11719370Spstinformation about the command. 11819370Spst.It Ic addvars Ar name Ns Oo \&= Ns Ar value Oc Ns Op ,... 11919370Spst.It Ic rmvars Ar name Ns Op ,... 12019370Spst.It Ic clearvars 12119370Spst.It Ic showvars 12219370SpstThe arguments to this command consist of a list of 12319370Spstitems of the form 12419370Spst.Ar name Ns Op \&= Ns Ar value , 12519370Spstwhere the 12619370Spst.No \&= Ns Ar value 12719370Spstis ignored, and can be omitted, 12819370Spstin requests to the server to read variables. 12919370SpstThe 13019370Spst.Nm 13119370Spstutility maintains an internal list in which data to be included in 13219370Spstmessages can be assembled, and displayed or set using the 13319370Spst.Ic readlist 13419370Spstand 13519370Spst.Ic writelist 13619370Spstcommands described below. 13719370SpstThe 13819370Spst.Ic addvars 13919370Spstcommand allows variables and their optional values to be added to 14019370Spstthe list. 14119370SpstIf more than one variable is to be added, the list should 14219370Spstbe comma\-separated and not contain white space. 14319370SpstThe 14419370Spst.Ic rmvars 14519370Spstcommand can be used to remove individual variables from the list, 14619370Spstwhile the 14719370Spst.Ic clearvars 14819370Spstcommand removes all variables from the 14919370Spstlist. 15019370SpstThe 15119370Spst.Ic showvars 15219370Spstcommand displays the current list of optional variables. 15319370Spst.It Ic authenticate Op Cm yes Ns | Ns Cm no 15419370SpstNormally 15519370Spst.Nm 15619370Spstdoes not authenticate requests unless 15719370Spstthey are write requests. 15819370SpstThe command 15919370Spst.Ic authenticate Cm yes 16019370Spstcauses 16119370Spst.Nm 16219370Spstto send authentication with all requests it 16319370Spstmakes. 16419370SpstAuthenticated requests causes some servers to handle 16519370Spstrequests slightly differently. 16619370SpstThe command 16719370Spst.Ic authenticate 16819370Spstcauses 16919370Spst.Nm 17019370Spstto display whether or not 17119370Spstit is currently authenticating requests. 17219370Spst.It Ic cooked 17319370SpstCauses output from query commands to be "cooked", so that 17419370Spstvariables which are recognized by 17519370Spst.Nm 17619370Spstwill have their 17719370Spstvalues reformatted for human consumption. 17819370SpstVariables which 17919370Spst.Nm 18019370Spstcould not decode completely are 18119370Spstmarked with a trailing 18219370Spst.Ql \&? . 18319370Spst.It Ic debug Op Cm more Ns | Ns Cm less Ns | Ns Cm off 18419370SpstWith no argument, displays the current debug level. 18519370SpstOtherwise, the debugging level is changed as indicated. 18619370Spst.It Ic delay Op Ar milliseconds 18719370SpstSpecify a time interval to be added to timestamps included in 18819370Spstrequests which require authentication. 18919370SpstThis is used to enable 19019370Spst(unreliable) server reconfiguration over long delay network paths 19119370Spstor between machines whose clocks are unsynchronized. 19219370SpstActually the 19319370Spstserver does not now require timestamps in authenticated requests, 19419370Spstso this command may be obsolete. 19519370SpstWithout any arguments, displays the current delay. 19619370Spst.It Ic drefid Op Cm hash Ns | Ns Cm ipv4 19719370SpstDisplay refids as IPv4 or hash. 19819370SpstWithout any arguments, displays whether refids are shown as IPv4 19919370Spstaddresses or hashes. 20019370Spst.It Ic exit 20119370SpstExit 20219370Spst.Nm . 20319370Spst.It Ic host Op Ar name 20419370SpstSet the host to which future queries will be sent. 20519370SpstThe 20619370Spst.Ar name 20719370Spstmay be either a host name or a numeric address. 20819370SpstWithout any arguments, displays the current host. 20919370Spst.It Ic hostnames Op Cm yes Ns | Ns Cm no 21019370SpstIf 21119370Spst.Cm yes 21219370Spstis specified, host names are printed in 21319370Spstinformation displays. 21419370SpstIf 21519370Spst.Cm no 21619370Spstis specified, numeric 21719370Spstaddresses are printed instead. 21819370SpstThe default is 21919370Spst.Cm yes , 22019370Spstunless 22119370Spstmodified using the command line 22219370Spst.Fl n 22319370Spstswitch. 22419370SpstWithout any arguments, displays whether host names or numeric addresses 22519370Spstare shown. 22619370Spst.It Ic keyid Op Ar keyid 22719370SpstThis command allows the specification of a key number to be 22819370Spstused to authenticate configuration requests. 22919370SpstThis must correspond 23019370Spstto the 23119370Spst.Cm controlkey 23219370Spstkey number the server has been configured to use for this 23319370Spstpurpose. 23419370SpstWithout any arguments, displays the current 23519370Spst.Ar keyid . 23619370Spst.It Ic keytype Op Ar digest 23719370SpstSpecify the digest algorithm to use for authenticating requests, with default 23819370Spst.Cm MD5 . 23919370SpstIf 24019370Spst.Nm 24119370Spstwas built with OpenSSL support, and OpenSSL is installed, 24219370Spst.Ar digest 24319370Spstcan be any message digest algorithm supported by OpenSSL. 24419370SpstIf no argument is given, the current 24519370Spst.Ic keytype Ar digest 24619370Spstalgorithm used is displayed. 24719370Spst.It Ic ntpversion Op Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3 Ns | Ns Cm 4 24819370SpstSets the NTP version number which 24919370Spst.Nm 25019370Spstclaims in 25119370Spstpackets. 25219370SpstDefaults to 3, and note that mode 6 control messages (and 25319370Spstmodes, for that matter) didn't exist in NTP version 1. 25419370SpstThere appear 25519370Spstto be no servers left which demand version 1. 25619370SpstWith no argument, displays the current NTP version that will be used 25719370Spstwhen communicating with servers. 25819370Spst.It Ic passwd 25919370SpstThis command prompts you to type in a password (which will not 26019370Spstbe echoed) which will be used to authenticate configuration 26119370Spstrequests. 26219370SpstThe password must correspond to the key configured for 26319370Spstuse by the NTP server for this purpose if such requests are to be 26419370Spstsuccessful. 26519370Spst.It Ic poll Oo Ar n Oc Op Cm verbose 26619370SpstPoll an NTP server in client mode 26719370Spst.Ar n 26819370Spsttimes. 26919370SpstPoll not implemented yet. 27019370Spst.It Ic quit 27119370SpstExit 27219370Spst.Nm . 27319370Spst.It Ic raw 27419370SpstCauses all output from query commands is printed as received 27519370Spstfrom the remote server. 27619370SpstThe only formating/interpretation done on 27719370Spstthe data is to transform nonascii data into a printable (but barely 27819370Spstunderstandable) form. 27919370Spst.It Ic timeout Op Ar milliseconds 28019370SpstSpecify a timeout period for responses to server queries. 28119370SpstThe 28219370Spstdefault is about 5000 milliseconds. 28319370SpstWithout any arguments, displays the current timeout period. 28419370SpstNote that since 28519370Spst.Nm 28619370Spstretries each query once after a timeout, the total waiting time for 28719370Spsta timeout will be twice the timeout value set. 28819370Spst.It Ic version 28919370SpstDisplay the version of the 29019370Spst.Nm 29119370Spstprogram. 29219370Spst.El 29319370Spst.Ss "Control Message Commands" 29419370SpstAssociation ids are used to identify system, peer and clock variables. 29519370SpstSystem variables are assigned an association id of zero and system name 29619370Spstspace, while each association is assigned a nonzero association id and 29719370Spstpeer namespace. 29819370SpstMost control commands send a single message to the server and expect a 29919370Spstsingle response message. 30019370SpstThe exceptions are the 30119370Spst.Ic peers 30219370Spstcommand, which sends a series of messages, 30319370Spstand the 30419370Spst.Ic mreadlist 30519370Spstand 30619370Spst.Ic mreadvar 30719370Spstcommands, which iterate over a range of associations. 30819370Spst.Bl -tag -width "something" -compact -offset indent 30919370Spst.It Ic apeers 31019370SpstDisplay a list of peers in the form: 31119370Spst.Dl [tally]remote refid assid st t when pool reach delay offset jitter 31219370Spstwhere the output is just like the 31319370Spst.Ic peers 31419370Spstcommand except that the 31519370Spst.Cm refid 31619370Spstis displayed in hex format and the association number is also displayed. 31719370Spst.It Ic associations 31819370SpstDisplay a list of mobilized associations in the form: 31919370Spst.Dl ind assid status conf reach auth condition last_event cnt 32019370Spst.Bl -column -offset indent ".Sy Variable" "see the select field of the peer status word" 32119370Spst.It Sy Variable Ta Sy Description 32219370Spst.It Cm ind Ta index on this list 32319370Spst.It Cm assid Ta association id 32419370Spst.It Cm status Ta peer status word 32519370Spst.It Cm conf Ta Cm yes : No persistent, Cm no : No ephemeral 32619370Spst.It Cm reach Ta Cm yes : No reachable, Cm no : No unreachable 32719370Spst.It Cm auth Ta Cm ok , Cm yes , Cm bad No and Cm none 32819370Spst.It Cm condition Ta selection status \&(see the Cm select No field of the peer status word\&) 32919370Spst.It Cm last_event Ta event report \&(see the Cm event No field of the peer status word\&) 33019370Spst.It Cm cnt Ta event count \&(see the Cm count No field of the peer status word\&) 33119370Spst.El 33219370Spst.It Ic authinfo 33319370SpstDisplay the authentication statistics counters: 33419370Spsttime since reset, stored keys, free keys, key lookups, keys not found, 33519370Spstuncached keys, expired keys, encryptions, decryptions. 33619370Spst.It Ic clocklist Op Ar associd 33719370Spst.It Ic cl Op Ar associd 33819370SpstDisplay all clock variables in the variable list for those associations 33919370Spstsupporting a reference clock. 34019370Spst.It Ic clockvar Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,... 34119370Spst.It Ic cv Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,... 34219370SpstDisplay a list of clock variables for those associations supporting a 34319370Spstreference clock. 34419370Spst.It Ic :config Ar "configuration command line" 34519370SpstSend the remainder of the command line, including whitespace, to the 34619370Spstserver as a run\-time configuration command in the same format as a line 34719370Spstin the configuration file. 34819370SpstThis command is experimental until further notice and clarification. 34919370SpstAuthentication is of course required. 35019370Spst.It Ic config\-from\-file Ar filename 35119370SpstSend each line of 35219370Spst.Ar filename 35319370Spstto the server as run\-time configuration commands in the same format as 35419370Spstlines in the configuration file. 35519370SpstThis command is experimental until further notice and clarification. 35619370SpstAuthentication is required. 35719370Spst.It Ic ifstats 35819370SpstDisplay status and statistics counters for each local network interface address: 35919370Spstinterface number, interface name and address or broadcast, drop, flag, 36019370Spstttl, mc, received, sent, send failed, peers, uptime. 36119370SpstAuthentication is required. 36219370Spst.It Ic iostats 36319370SpstDisplay network and reference clock I/O statistics: 36419370Spsttime since reset, receive buffers, free receive buffers, used receive buffers, 36519370Spstlow water refills, dropped packets, ignored packets, received packets, 36619370Spstpackets sent, packet send failures, input wakeups, useful input wakeups. 36719370Spst.It Ic kerninfo 36819370SpstDisplay kernel loop and PPS statistics: 36919370Spstassocid, status, pll offset, pll frequency, maximum error, 37019370Spstestimated error, kernel status, pll time constant, precision, 37119370Spstfrequency tolerance, pps frequency, pps stability, pps jitter, 37219370Spstcalibration interval, calibration cycles, jitter exceeded, 37319370Spststability exceeded, calibration errors. 37419370SpstAs with other ntpq output, times are in milliseconds; very small values 37519370Spstmay be shown as exponentials. 37619370SpstThe precision value displayed is in milliseconds as well, unlike the 37719370Spstprecision system variable. 37819370Spst.It Ic lassociations 37919370SpstPerform the same function as the associations command, except display 38019370Spstmobilized and unmobilized associations, including all clients. 38119370Spst.It Ic lopeers Op Fl 4 Ns | Ns Fl 6 38219370SpstDisplay a list of all peers and clients showing 38319370Spst.Cm dstadr 38419370Spst(associated with the given IP version). 38519370Spst.It Ic lpassociations 38619370SpstDisplay the last obtained list of associations, including all clients. 38719370Spst.It Ic lpeers Op Fl 4 Ns | Ns Fl 6 38819370SpstDisplay a list of all peers and clients (associated with the given IP version). 38919370Spst.It Ic monstats 39019370SpstDisplay monitor facility status, statistics, and limits: 39119370Spstenabled, addresses, peak addresses, maximum addresses, 39219370Spstreclaim above count, reclaim older than, kilobytes, maximum kilobytes. 39319370Spst.It Ic mreadlist Ar associdlo Ar associdhi 39419370Spst.It Ic mrl Ar associdlo Ar associdhi 39519370SpstPerform the same function as the 39619370Spst.Ic readlist 39719370Spstcommand for a range of association ids. 39819370Spst.It Ic mreadvar Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,... 39919370SpstThis range may be determined from the list displayed by any 40019370Spstcommand showing associations. 40119370Spst.It Ic mrv Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,... 40219370SpstPerform the same function as the 40319370Spst.Ic readvar 40419370Spstcommand for a range of association ids. 40519370SpstThis range may be determined from the list displayed by any 40619370Spstcommand showing associations. 40719370Spst.It Xo Ic mrulist Oo Cm limited | Cm kod | Cm mincount Ns \&= Ns Ar count | 40819370Spst.Cm laddr Ns \&= Ns Ar localaddr | Cm sort Ns \&= Ns Oo \&\- Oc Ns Ar sortorder | 40919370Spst.Cm resany Ns \&= Ns Ar hexmask | Cm resall Ns \&= Ns Ar hexmask Oc 41019370Spst.Xc 41119370SpstDisplay traffic counts of the most recently seen source addresses 41219370Spstcollected and maintained by the monitor facility. 41319370SpstWith the exception of 41419370Spst.Cm sort Ns \&= Ns Oo \&\- Oc Ns Ar sortorder , 41519370Spstthe options filter the list returned by 41619370Spst.Xr ntpd 8 . 41719370SpstThe 41819370Spst.Cm limited 41919370Spstand 42019370Spst.Cm kod 42119370Spstoptions return only entries representing client addresses from which the 42219370Spstlast packet received triggered either discarding or a KoD response. 42319370SpstThe 42419370Spst.Cm mincount Ns = Ns Ar count 42519370Spstoption filters entries representing less than 42619370Spst.Ar count 42719370Spstpackets. 42819370SpstThe 42919370Spst.Cm laddr Ns = Ns Ar localaddr 43019370Spstoption filters entries for packets received on any local address other than 43119370Spst.Ar localaddr . 43219370Spst.Cm resany Ns = Ns Ar hexmask 43319370Spstand 43419370Spst.Cm resall Ns = Ns Ar hexmask 43519370Spstfilter entries containing none or less than all, respectively, of the bits in 43619370Spst.Ar hexmask , 43719370Spstwhich must begin with 43819370Spst.Cm 0x . 43919370SpstThe 44019370Spst.Ar sortorder 44119370Spstdefaults to 44219370Spst.Cm lstint 44319370Spstand may be 44419370Spst.Cm addr , 44519370Spst.Cm avgint , 44619370Spst.Cm count , 44719370Spst.Cm lstint , 44819370Spstor any of those preceded by 44919370Spst.Ql \&\- 45019370Spstto reverse the sort order. 45119370SpstThe output columns are: 45219370Spst.Bl -tag -width "something" -compact -offset indent 45319370Spst.It Column 45419370SpstDescription 45519370Spst.It Ic lstint 45619370SpstInterval in seconds between the receipt of the most recent packet from 45719370Spstthis address and the completion of the retrieval of the MRU list by 45819370Spst.Nm . 45919370Spst.It Ic avgint 46019370SpstAverage interval in s between packets from this address. 46119370Spst.It Ic rstr 46219370SpstRestriction flags associated with this address. 46319370SpstMost are copied unchanged from the matching 46419370Spst.Ic restrict 46519370Spstcommand, however 0x400 (kod) and 0x20 (limited) flags are cleared unless 46619370Spstthe last packet from this address triggered a rate control response. 46719370Spst.It Ic r 46819370SpstRate control indicator, either 46919370Spsta period, 47019370Spst.Ic L 47119370Spstor 47219370Spst.Ic K 47319370Spstfor no rate control response, 47419370Spstrate limiting by discarding, or rate limiting with a KoD response, respectively. 47519370Spst.It Ic m 47619370SpstPacket mode. 47719370Spst.It Ic v 47819370SpstPacket version number. 47919370Spst.It Ic count 48019370SpstPackets received from this address. 48119370Spst.It Ic rport 48219370SpstSource port of last packet from this address. 48319370Spst.It Ic remote address 48419370Spsthost or DNS name, numeric address, or address followed by 48519370Spstclaimed DNS name which could not be verified in parentheses. 48619370Spst.El 48719370Spst.It Ic opeers Op Fl 4 | Fl 6 48819370SpstObtain and print the old\-style list of all peers and clients showing 48919370Spst.Cm dstadr 49019370Spst(associated with the given IP version), 49119370Spstrather than the 49219370Spst.Cm refid . 49319370Spst.It Ic passociations 49419370SpstPerform the same function as the 49519370Spst.Ic associations 49619370Spstcommand, 49719370Spstexcept that it uses previously stored data rather than making a new query. 49819370Spst.It Ic peers 49919370SpstDisplay a list of peers in the form: 50019370Spst.Dl [tally]remote refid st t when pool reach delay offset jitter 50119370Spst.Bl -tag -width "something" -compact -offset indent 50219370Spst.It Variable 50319370SpstDescription 50419370Spst.It Cm [tally] 50519370Spstsingle\-character code indicating current value of the 50619370Spst.Ic select 50719370Spstfield of the 50819370Spst.Lk decode.html#peer "peer status word" 50919370Spst.It Cm remote 51019370Spsthost name (or IP number) of peer. 51119370SpstThe value displayed will be truncated to 15 characters unless the 51219370Spst.Nm 51319370Spst.Fl w 51419370Spstoption is given, in which case the full value will be displayed 51519370Spston the first line, and if too long, 51619370Spstthe remaining data will be displayed on the next line. 51719370Spst.It Cm refid 51819370Spstsource IP address or 51919370Spst.Lk decode.html#kiss "'kiss code" 52019370Spst.It Cm st 52119370Spststratum: 0 for local reference clocks, 1 for servers with local 52219370Spstreference clocks, ..., 16 for unsynchronized server clocks 52319370Spst.It Cm t 52419370Spst.Ic u : 52519370Spstunicast or manycast client, 52619370Spst.Ic b : 52719370Spstbroadcast or multicast client, 52819370Spst.Ic p : 52919370Spstpool source, 53019370Spst.Ic l : 53119370Spstlocal (reference clock), 53219370Spst.Ic s : 53319370Spstsymmetric (peer), 53419370Spst.Ic A : 53519370Spstmanycast server, 53619370Spst.Ic B : 53719370Spstbroadcast server, 53819370Spst.Ic M : 53919370Spstmulticast server 54019370Spst.It Cm when 54119370Spsttime in seconds, minutes, hours, or days since the last packet 54219370Spstwas received, or 54319370Spst.Ql \&\- 54419370Spstif a packet has never been received 54519370Spst.It Cm poll 54619370Spstpoll interval (s) 54719370Spst.It Cm reach 54819370Spstreach shift register (octal) 54919370Spst.It Cm delay 55019370Spstroundtrip delay 55119370Spst.It Cm offset 55219370Spstoffset of server relative to this host 55319370Spst.It Cm jitter 55419370Spstoffset RMS error estimate. 55519370Spst.El 55619370Spst.It Ic pstats Ar associd 55719370SpstDisplay the statistics for the peer with the given 55819370Spst.Ar associd : 55919370Spstassocid, status, remote host, local address, time last received, 56019370Spsttime until next send, reachability change, packets sent, 56119370Spstpackets received, bad authentication, bogus origin, duplicate, 56219370Spstbad dispersion, bad reference time, candidate order. 56319370Spst.It Ic readlist Op Ar associd 56419370Spst.It Ic rl Op Ar associd 56519370SpstDisplay all system or peer variables. 56619370SpstIf the 56719370Spst.Ar associd 56819370Spstis omitted, it is assumed to be zero. 56919370Spst.It Ic readvar Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ... 57019370Spst.It Ic rv Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ... 57119370SpstDisplay the specified system or peer variables. 57219370SpstIf 57319370Spst.Ar associd 57419370Spstis zero, the variables are from the 57519370Spst.Sx System Variables 57619370Spstname space, otherwise they are from the 57719370Spst.Sx Peer Variables 57819370Spstname space. 57919370SpstThe 58019370Spst.Ar associd 58119370Spstis required, as the same name can occur in both spaces. 58219370SpstIf no 58319370Spst.Ar name 58419370Spstis included, all operative variables in the name space are displayed. 58519370SpstIn this case only, if the 58619370Spst.Ar associd 58719370Spstis omitted, it is assumed to be zero. 58819370SpstMultiple names are specified with comma separators and without whitespace. 58919370SpstNote that time values are represented in milliseconds 59019370Spstand frequency values in parts\-per\-million (PPM). 59119370SpstSome NTP timestamps are represented in the format 59219370Spst.Ar YYYY Ns Ar MM Ar DD Ar TTTT , 59319370Spstwhere 59419370Spst.Ar YYYY 59519370Spstis the year, 59619370Spst.Ar MM 59719370Spstthe month of year, 59819370Spst.Ar DD 59919370Spstthe day of month and 60019370Spst.Ar TTTT 601the time of day. 602.It Ic reslist 603Display the access control (restrict) list for 604.Nm . 605Authentication is required. 606.It Ic saveconfig Ar filename 607Save the current configuration, 608including any runtime modifications made by 609.Ic :config 610or 611.Ic config\-from\-file , 612to the NTP server host file 613.Ar filename . 614This command will be rejected by the server unless 615.Lk miscopt.html#saveconfigdir "saveconfigdir" 616appears in the 617.Xr ntpd 8 618configuration file. 619.Ar filename 620can use 621.Xr date 1 622format specifiers to substitute the current date and time, for 623example, 624.D1 Ic saveconfig Pa ntp\-%Y%m%d\-%H%M%S.conf . 625The filename used is stored in system variable 626.Cm savedconfig . 627Authentication is required. 628.It Ic sysinfo 629Display system operational summary: 630associd, status, system peer, system peer mode, leap indicator, 631stratum, log2 precision, root delay, root dispersion, 632reference id, reference time, system jitter, clock jitter, 633clock wander, broadcast delay, symm. auth. delay. 634.It Ic sysstats 635Display system uptime and packet counts maintained in the 636protocol module: 637uptime, sysstats reset, packets received, current version, 638older version, bad length or format, authentication failed, 639declined, restricted, rate limited, KoD responses, 640processed for time. 641.It Ic timerstats 642Display interval timer counters: 643time since reset, timer overruns, calls to transmit. 644.It Ic writelist Ar associd 645Set all system or peer variables included in the variable list. 646.It Ic writevar Ar associd Ar name Ns = Ns Ar value Op , ... 647Set the specified variables in the variable list. 648If the 649.Ar associd 650is zero, the variables are from the 651.Sx System Variables 652name space, otherwise they are from the 653.Sx Peer Variables 654name space. 655The 656.Ar associd 657is required, as the same name can occur in both spaces. 658Authentication is required. 659.El 660.Ss Status Words and Kiss Codes 661The current state of the operating program is shown 662in a set of status words 663maintained by the system. 664Status information is also available on a per\-association basis. 665These words are displayed by the 666.Ic readlist 667and 668.Ic associations 669commands both in hexadecimal and in decoded short tip strings. 670The codes, tips and short explanations are documented on the 671.Lk decode.html "Event Messages and Status Words" 672page. 673The page also includes a list of system and peer messages, 674the code for the latest of which is included in the status word. 675.Pp 676Information resulting from protocol machine state transitions 677is displayed using an informal set of ASCII strings called 678.Lk decode.html#kiss "kiss codes" . 679The original purpose was for kiss\-o'\-death (KoD) packets 680sent by the server to advise the client of an unusual condition. 681They are now displayed, when appropriate, 682in the reference identifier field in various billboards. 683.Ss System Variables 684The following system variables appear in the 685.Ic readlist 686billboard. 687Not all variables are displayed in some configurations. 688.Pp 689.Bl -tag -width "something" -compact -offset indent 690.It Variable 691Description 692.It Cm status 693.Lk decode.html#sys "system status word" 694.It Cm version 695NTP software version and build time 696.It Cm processor 697hardware platform and version 698.It Cm system 699operating system and version 700.It Cm leap 701leap warning indicator (0\-3) 702.It Cm stratum 703stratum (1\-15) 704.It Cm precision 705precision (log2 s) 706.It Cm rootdelay 707total roundtrip delay to the primary reference clock 708.It Cm rootdisp 709total dispersion to the primary reference clock 710.It Cm refid 711reference id or 712.Lk decode.html#kiss "kiss code" 713.It Cm reftime 714reference time 715.It Ic clock 716date and time of day 717.It Cm peer 718system peer association id 719.It Cm tc 720time constant and poll exponent (log2 s) (3\-17) 721.It Cm mintc 722minimum time constant (log2 s) (3\-10) 723.It Cm offset 724combined offset of server relative to this host 725.It Cm frequency 726frequency drift (PPM) relative to hardware clock 727.It Cm sys_jitter 728combined system jitter 729.It Cm clk_wander 730clock frequency wander (PPM) 731.It Cm clk_jitter 732clock jitter 733.It Cm tai 734TAI\-UTC offset (s) 735.It Cm leapsec 736NTP seconds when the next leap second is/was inserted 737.It Cm expire 738NTP seconds when the NIST leapseconds file expires 739.El 740The jitter and wander statistics are exponentially\-weighted RMS averages. 741The system jitter is defined in the NTPv4 specification; 742the clock jitter statistic is computed by the clock discipline module. 743.Pp 744When the NTPv4 daemon is compiled with the OpenSSL software library, 745additional system variables are displayed, 746including some or all of the following, 747depending on the particular Autokey dance: 748.Bl -tag -width "something" -compact -offset indent 749.It Variable 750Description 751.It Cm host 752Autokey host name for this host 753.It Cm ident 754Autokey group name for this host 755.It Cm flags 756host flags (see Autokey specification) 757.It Cm digest 758OpenSSL message digest algorithm 759.It Cm signature 760OpenSSL digest/signature scheme 761.It Cm update 762NTP seconds at last signature update 763.It Cm cert 764certificate subject, issuer and certificate flags 765.It Cm until 766NTP seconds when the certificate expires 767.El 768.Ss Peer Variables 769The following peer variables appear in the 770.Ic readlist 771billboard for each association. 772Not all variables are displayed in some configurations. 773.Pp 774.Bl -tag -width "something" -compact -offset indent 775.It Variable 776Description 777.It Cm associd 778association id 779.It Cm status 780.Lk decode.html#peer "peer status word" 781.It Cm srcadr 782source (remote) IP address 783.It Cm srcport 784source (remote) port 785.It Cm dstadr 786destination (local) IP address 787.It Cm dstport 788destination (local) port 789.It Cm leap 790leap indicator (0\-3) 791.It Cm stratum 792stratum (0\-15) 793.It Cm precision 794precision (log2 s) 795.It Cm rootdelay 796total roundtrip delay to the primary reference clock 797.It Cm rootdisp 798total root dispersion to the primary reference clock 799.It Cm refid 800reference id or 801.Lk decode.html#kiss "kiss code" 802.It Cm reftime 803reference time 804.It Cm rec 805last packet received time 806.It Cm reach 807reach register (octal) 808.It Cm unreach 809unreach counter 810.It Cm hmode 811host mode (1\-6) 812.It Cm pmode 813peer mode (1\-5) 814.It Cm hpoll 815host poll exponent (log2 s) (3\-17) 816.It Cm ppoll 817peer poll exponent (log2 s) (3\-17) 818.It Cm headway 819headway (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 824symmetric key id 825.It Cm offset 826filter offset 827.It Cm delay 828filter delay 829.It Cm dispersion 830filter dispersion 831.It Cm jitter 832filter jitter 833.It Cm bias 834unicast/broadcast bias 835.It Cm xleave 836interleave delay (see 837.Lk xleave.html "NTP Interleaved Modes" ) 838.El 839The 840.Cm bias 841variable is calculated when the first broadcast packet is received 842after the calibration volley. 843It represents the offset of the broadcast subgraph relative to the 844unicast subgraph. 845The 846.Cm xleave 847variable appears only for the interleaved symmetric and interleaved modes. 848It represents the internal queuing, buffering and transmission delays 849for the preceding packet. 850.Pp 851When the NTPv4 daemon is compiled with the OpenSSL software library, 852additional peer variables are displayed, including the following: 853.Bl -tag -width "something" -compact -offset indent 854.It Variable 855Description 856.It Cm flags 857peer flags (see Autokey specification) 858.It Cm host 859Autokey server name 860.It Cm flags 861peer flags (see Autokey specification) 862.It Cm signature 863OpenSSL digest/signature scheme 864.It Cm initsequence 865initial key id 866.It Cm initkey 867initial key index 868.It Cm timestamp 869Autokey signature timestamp 870.It Cm ident 871Autokey group name for this association 872.El 873.Ss Clock Variables 874The following clock variables appear in the 875.Ic clocklist 876billboard for each association with a reference clock. 877Not all variables are displayed in some configurations. 878.Bl -tag -width "something" -compact -offset indent 879.It Variable 880Description 881.It Cm associd 882association id 883.It Cm status 884.Lk decode.html#clock "clock status word" 885.It Cm device 886device description 887.It Cm timecode 888ASCII time code string (specific to device) 889.It Cm poll 890poll messages sent 891.It Cm noreply 892no reply 893.It Cm badformat 894bad format 895.It Cm baddata 896bad date or time 897.It Cm fudgetime1 898fudge time 1 899.It Cm fudgetime2 900fudge time 2 901.It Cm stratum 902driver stratum 903.It Cm refid 904driver reference id 905.It Cm flags 906driver flags 907.El 908.Sh "OPTIONS" 909.Bl -tag 910.It Fl 4 , Fl \-ipv4 911Force IPv4 name resolution. 912This option must not appear in combination with any of the following options: 913ipv6. 914.sp 915Force resolution of following host names on the command line 916to the IPv4 namespace. 917.It Fl 6 , Fl \-ipv6 918Force IPv6 name resolution. 919This option must not appear in combination with any of the following options: 920ipv4. 921.sp 922Force resolution of following host names on the command line 923to the IPv6 namespace. 924.It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd 925run a command and exit. 926This option may appear an unlimited number of times. 927.sp 928The following argument is interpreted as an interactive format command 929and is added to the list of commands to be executed on the specified 930host(s). 931.It Fl d , Fl \-debug\-level 932Increase debug verbosity level. 933This option may appear an unlimited number of times. 934.sp 935.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number 936Set the debug verbosity level. 937This option may appear an unlimited number of times. 938This option takes an integer number as its argument. 939.sp 940.It Fl i , Fl \-interactive 941Force ntpq to operate in interactive mode. 942This option must not appear in combination with any of the following options: 943command, peers. 944.sp 945Force \fBntpq\fP to operate in interactive mode. 946Prompts will be written to the standard output and 947commands read from the standard input. 948.It Fl n , Fl \-numeric 949numeric host addresses. 950.sp 951Output all host addresses in dotted\-quad numeric format rather than 952converting to the canonical host names. 953.It Fl \-old\-rv 954Always output status line with readvar. 955.sp 956By default, \fBntpq\fP now suppresses the \fBassocid=...\fP 957line 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. 960This option causes \fBntpq\fP to include both lines of output 961for a single\-variable \fBreadvar\fP. 962Using an environment variable to 963preset this option in a script will enable both older and 964newer \fBntpq\fP to behave identically in this regard. 965.It Fl p , Fl \-peers 966Print a list of the peers. 967This option must not appear in combination with any of the following options: 968interactive. 969.sp 970Print a list of the peers known to the server as well as a summary 971of their state. This is equivalent to the 'peers' interactive command. 972.It Fl r Ar keyword , Fl \-refid Ns = Ns Ar keyword 973Set default display type for S2+ refids. 974This option takes a keyword as its argument. The argument sets an enumeration value that can 975be tested by comparing them against the option value macro. 976The available keywords are: 977.in +4 978.nf 979.na 980hash ipv4 981.fi 982or their numeric equivalent. 983.in -4 984.sp 985The default 986.Ar keyword 987for this option is: 988.ti +4 989 ipv4 990.sp 991Set the default display format for S2+ refids. 992.It Fl w , Fl \-wide 993Display the full 'remote' value. 994.sp 995Display the full value of the 'remote' value. If this requires 996more than 15 characters, display the full value, emit a newline, 997and continue the data display properly indented on the next line. 998.It Fl \&? , Fl \-help 999Display usage information and exit. 1000.It Fl \&! , Fl \-more\-help 1001Pass the extended usage information through a pager. 1002.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc 1003Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP 1004configuration file listed in the \fBOPTION PRESETS\fP section, below. 1005The command will exit after updating the config file. 1006.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts 1007Load options from \fIcfgfile\fP. 1008The \fIno\-load\-opts\fP form will disable the loading 1009of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, 1010out of order. 1011.It Fl \-version Op Brq Ar v|c|n 1012Output version of program and exit. The default mode is `v', a simple 1013version. The `c' mode will print copyright information and `n' will 1014print the full copyright notice. 1015.El 1016.Sh "OPTION PRESETS" 1017Any option that is not marked as \fInot presettable\fP may be preset 1018by loading values from configuration ("RC" or ".INI") file(s) and values from 1019environment variables named: 1020.nf 1021 \fBNTPQ_<option\-name>\fP or \fBNTPQ\fP 1022.fi 1023.ad 1024The environmental presets take precedence (are processed later than) 1025the configuration files. 1026The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". 1027If any of these are directories, then the file \fI.ntprc\fP 1028is searched for within those directories. 1029.Sh "ENVIRONMENT" 1030See \fBOPTION PRESETS\fP for configuration environment variables. 1031.Sh "FILES" 1032See \fBOPTION PRESETS\fP for configuration files. 1033.Sh "EXIT STATUS" 1034One of the following exit values will be returned: 1035.Bl -tag 1036.It 0 " (EXIT_SUCCESS)" 1037Successful program execution. 1038.It 1 " (EXIT_FAILURE)" 1039The operation failed or the command syntax was not valid. 1040.It 66 " (EX_NOINPUT)" 1041A specified configuration file could not be loaded. 1042.It 70 " (EX_SOFTWARE)" 1043libopts had an internal operational error. Please report 1044it to autogen\-users@lists.sourceforge.net. Thank you. 1045.El 1046.Sh "AUTHORS" 1047The University of Delaware and Network Time Foundation 1048.Sh "COPYRIGHT" 1049Copyright (C) 1992\-2020 The University of Delaware and Network Time Foundation all rights reserved. 1050This program is released under the terms of the NTP license, <http://ntp.org/license>. 1051.Sh "BUGS" 1052Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 1053.Sh "NOTES" 1054This manual page was \fIAutoGen\fP\-erated from the \fBntpq\fP 1055option definitions. 1056