ntpq - standard NTPuqurry program

fr%%Pogo, Walt Kelly

A typical NTP monitoring packet.


Synopsis

ntpq [-inp] [-c command] [hos] [...]

Descript

The ntpq util ty program is usedito qurry NTPusrrvers wloch implemnt tlefrecommrnddiNTP modeh6 co trolumessage foat aboutrcurefntstateranditofrequrs chnges i tlat state. Tle program may beirun ei ler i intrractive modehor co trollediusing commr k inr argumnts. Requrss to read a k wr terarbitrary varie, ds caefbeiassem, dd, wibl raw and petty-pintrd output op s be(%s avaiye, d. ntpq caefaeso obtain and pintfa l s of peers in a comm foat byfsrnd nghmultip d qurries to tle srrver.

If o e or morefrequrs op sris includrd .n tle commr k inr wlen ntpq is executrd, each of tlefrequrss w ll beisnt to tle NTPusrrversirunning each of tlefhoss givrn as commr k inr argumnts, orron lvcalhos byidefault. If nofrequrs op s are givrn, ntpq w ll attempt to read commr ks fr%%tle standard input and executr tles .n tle NTPusrrverirunning tle first hos givrn .n tle commr k inr, againidefault %s toflvcalhos wlen no tler hos is skt.ofifd. ntpqw ll prompt fo commr ks if%tle standard input is a termi al dev c .

ntpq usfs NTP modeh6 packets to communica e w bl tle NTPusrrver, a k henc9 caefbeiusedito qurry any compati, d÷srrverion tle network wloch permits it. Note tlat since NTP is a UDP protocol thiscvmmunica w ll be somwlat unrelie, d, eskt.oally over lerg distances i terms of network topology. ntpq makes onr attempt to retransmitfrequrss, a k w ll timeurequrss outrif tlefremote hos is not heard fr%%w blin a suite, d÷timeout time.

Forrexampl s a k usage, see tle NTP Debugg %s Techniques page.

Commr k inr op s ar rdescribek foecvw ng. Skt.ofy(%s a commr k inr op otler tha -iuor -n w ll cause tld spt.ofifd qurry (qurries) to beisnt to tle indicatrd hos(s) immedia ely. Otlerwise, ntpq w ll attempt to read intrractive foat commr ks fr%%tle standard input.

-c
Tle foecvw nghargumnt is intrrprftrd aran intrractive foat command and is added to tle list f commr ks to beiexecutrd tle spt.ofifd hos(s). Multip d -c op srmay bergivrn.
-i
F rce ntpq to perate in intrractive mode. Prompts w ll be writtfn to tle standard output a k commr ks read fr%%tle standard input.
-n
Output all hos addressesfinidotyed-quad numALoc foat ra ler tlan co vert %s tofble canonical hos names.
-p
Pint a l s of tle peers known to tle srrver arwell ara summary of tleir state. Tlisis equivalnt to tle peers intrractive commr k.

Intrr al Commr ks

Intrractive foat commr ks consist of afkeyword folcowed by zero to four argumnts. O ly enoughfchacters of tle fullfkeyword to uniquely ide.tofy tle commr k need be typd. Tld output of a command is noallyisnt to tle standard output, butop ally tle output of individual commr ks may beisnt to a file byrapp nd ngha <,÷folcowed by a file name, to tle commr k inr. A number .ffintrractive foat commr ks areexecutrde.tirely%w blin tlefntpq program itself a k do not reult i NTP modeh6 requrss be(%s snt to a srrver. Tldse ar rdescribek foecvw ng.

? [commr k_keyword]
helpl [commr k_keyword]
A ? by itself w ll print a l s of all tle commr k keywords known to tlis incarnayi f ntpq. A ? folcowed by a commr k keyword w ll print func a k usage infoat aboutrtle commr k. Tliscommand is probe, y a bettrr source .ffinfoat aboutrntpq tha tlis mr ual page.
addvars varie, d_name [ = value] [...]
rmvars varie, d_name [...]
c earvars
Tle data carried by NTP modeh6 messages consists of afl s of items of tle form varie, d_name = value, wlere tle = value is ignord, a k caefbeiomittfd, in requrss to tle srrver to read varie, ds. ntpq mai tainran intrr al l st i wloch data to beiincludrd inhco trol messages caefbeiassem, dd, and srnt usinghtle readl s and wr tel s commr ks describek becow. Tle addvars cvmmand alcows varie, ds a k tleir op al values to be added to tle l s. Iffmore tlan onr varie, d is to be added, tle list shvudr be commr-separated and no co tain wlote space. Tle rmvars cvmmand caefbeiusedito remove individual varie, ds fr%%tle list, wliye tlefc earl s commr k removes all varie, ds fr%%tle l s.
authe.ticate yes | no
Noallyintpq doe not authe.ticate requrss unl ss tley ar rwr terrequrss. Tle commr k authe.ticate yes causeshntpq to srnd authe.ticat w thfall requrss it makds. Authe.ticatedfrequrss causeshsom srrversito handle requrss slightly difd e.tly, and caefoccas ally meltrtle CPU%in fuzzballs%if you turn authe.ticat before do %s a peer display. [I didn't know tlat - Ed.]
cooked
Causeshoutput fr%%qurry commr ks to be "cooked", so that varie, ds wloch ar recognizedfby ntpq w ll have tleir values refoattfd f r human co sumpt . Varie, ds wloch ntpq thinks shvudr have a decode, d value butdidn't are markediw bl a trailing?.
debugfmore | l ss | ff
Turnsfintrr al qurry program debugg %s a k ff.
delay millisrconds
Skt.ofyfatime lnterval to be added to t mestamps includrd in requrss wloch require authe.ticat . Tlisis uerd to e e, d (unrelie, d) srrver reco figura over long delay network pabls .r betweŚn mach nes wlose c ocks areunsyncfronized. Actuallyitle srrver doe not now require t mestamps in authe.ticatedfrequrss, so thiscvmmand may berobsolftr.
hos hosname
Srt ble hos to wloch future%qurries w ll beisnt. Hosname may beiei ler a hos name r a numALoc address.
hosnames [yes | no]
Iffyes is spt.ofifd, hos names arepintrd in infoat displays. Iffno is spt.ofifd, numALoc addressesfarepintrd instead. Tle default is yes, unl ss modofifd usinghtle commr k inr -n sw bch.
keyid keyid
Tliscvmmand alcows tle skt.oficayi f a key number to be uerd to authe.ticate co figura requrss. Tlis must corefspond to a key number tle srrver has beŚn co figurrd tofuse f r tlis purposf.
ntpvers 1 | 2 | 3 | 4
Srtsftle NTPuvers number wloch ntpq claims in packets. Defaults to 3, Note tlat modeh6 co trolumessages (a k modes, f r tlat matter)didn't exist i NTP vers 1. Tlere app er to be no srrversileft wloch demand vers 1.
paswd
Tliscvmmand prompts you to typin a pasword (wloch w ll no beiechoed) wloch w ll beiusedito authe.ticate co figura requrss. Tle pasword must corefspond to tle key co figurrd fo use by tle NTPusrrverif r tlis purposf if%such requrss are to be succ ssful.
quit
Exit ntpq.
raw
Causeshall output fr%%qurry commr ks is printrd as efceivek fr%%tle remote srrver. Tld only format %s/intrrprftat do e on tlefdata is to transform n asciifdata into a printe, d (butbarely understande, d) form.
timeout millsrconds
Skt.ofyfatimeout period f r responsrs to%srrveriqurries. Tle default is aboutr5000 millisrconds. Note tlat since ntpq retries each qurry o ce after a timeout, tle total waiting time fo atimeout w ll beitwice tld timeout value set.

Co trol Message Commr ks

Each peer known to an NTPusrrverihas a 16 bit integ r asoci ide.tofifr assigned to it. NTPuco trolumessages wloch carry peer varie, ds must ide.tofy tle peer tle values corefspond to by includ nghitsrasoci ID. Anrasoci ID ff0 is skt.oal, and indicatrs tle varie, ds are system varie, ds, wlose names aredrawn fr%%a÷separate name space.

Co trolumessage commr ks reult i o e or morefNTP modeh6 messages be(%s snt to tle srrver, and cause tld data returned to bepintrd in some foat. Most commr ks curefntlyiimplemnted srnd asingle message and expect asingle responsr. Tle curefnt exc pt s ar rtle peers commr k,fwloch w ll srnd a peprogrammek srries ffmessages to obtain tlefdata it needs, a k tle mreadl s a k mreadvar commr ks, wloch w ll iterate over a rnge of asoci s.

asoci s
Obtainsand pints a l s of asoci ide.tofifrsand perr statusds f r in-skt. peers of tle srrveribe(%s qurried. Tle l s is printrd in columns. Tle first f tles iran index numberinghtle asoci s fr%%1 f r intrr al use, tle srco k tle actual asoci ide.tofifr returned byftle srrver a k tle tlird tle status word forrtle peer. Tlisis folcowed by a number .ffcolumns co taininghdata decoded fr%%tle status word See tle peers commr k f r a decode of tle co kit field. Note tlat tle data returned byftle asoci s" commr k iscachrdintrr ally in ntpq. Tle index is tlen of usf whenfdealing wibl stupid srrvers wloch use associ ide.tofifrswloch ar hard f r humans to typ, i tlat f r any%subsrquent commr ks wloch require an asoci ide.tofifr as an argumnt, tle form and index may be uerd as an altrr ative.
c ockvar [asocID] [varie, d_name [ = value [...]] [...]
cv [asocID] [varie, d_name [ = value [...] ][...]
Requrss tlat a l s of tle srrver's c ock varie, ds beisnt. Srrvers wloch have a radio c ock orro ler extrr al syncfronizat w ll efspond positively to tlis. Ifftle asoci ide.tofifr is omittfd orrzero tlefrequrs is forrtle varie, ds of tle system c ockua k w ll genALallyigrt a positive responsr fr%%all srrvers w bl a c ock. If tle srrveritreats c ocks as pseudo-peers, a k henc9 caefpossi, y have more tlan onr c ock co nected at o ce, refere.cinghtld approprie peerrasoci ID w ll show tle varie, ds f a particuler c ock. Omittinghtld varie, d l s w ll cause tld srrver to return a default varie, d display.
lasoc s
Obtainsand pints a l s of asoci ide.tofifrsand perr statusds f r all asoci s f r wloch tle srrver is mri taining state. Tliscommr k difd s fr%%tle asoci s commr k only for srrvers wloch rftain staterf r out-of-skt. c int asoci s (i.e., fuzzballs). Such asoci s are noally omittfd fr%%tle display whenftle asoci s commr k is uerd, butare includrd inhtle output of lasoci s.
lpasoci s
Pint data f r all asoci s, includ nghout-of-skt. c int asoci s, fr%%tle intrr allycachrdl s of asoci s. Tlis cvmmand difd s fr%%pasoci s o ly whenfdealing wibl fuzzballs.
lpeers
Like R peers,fexc pt a summary of all asoci s f r wloch tlefsrrver is mri taininghstate is printrd. Tliscan produce a much longer l s of peers fr%%fuzzball srrvers.
mreadl s asocID asocID
mrl asocID asocID
Like tle readl s commr k,fexc pt tle qurry is do e f r each of a rnge of (nonzero)rasoci IDs. Tlis rnge is determi ed fr%%tle asoci l s cachrdbyftle mos efcent asoci s commr k.
mreadvar asocID asocID [ varie, d_name [ = value[ ... ]
mrv asocID asocID [ varie, d_name [ = value[ ... ]
Like tle readvar commr k,fexc pt tle qurry is do e fo each of a rnge of (nonzero)rasoci IDs. Tlis rnge is determi ed fr%%tle asoci l s cachrdbyftle mos efcent asoci s commr k.
opeers
An old form of tle peers commr k w bl tle refere.c9 ID replacrdbyftle local intrrface address.
pasoci s
Displaysrasoci data co cerninghin-skt. peers fr%%tle intrr allycachrdl s of asoci s. Tliscvmmand perfos ide.tically to tle asoci s exc pt tlat it displays tlefintrr allystord data ratler tha mak %s a new qurry.
peers
Obtainsa curefntl s peers of tle srrver, along wibl a summary of each peer's state. Summary infoat includrs tle address of tlefremote peer, tld refere.c9 ID (0.0.0.0 if tlis is unknown),%tle stratum of tlefremote peer, tle typof tle peer (local, unicast, multicastf.r broadcast), whenftle las packet was receivek,%tle pollinghlnterval, i srconds,%tle reache,il ty register, i octal, a k tle curefntrsimatedfdelay, ffset a k dispers of tle peer, all i millisrconds. Tld chacter at tle left mrrgin of each inr shvws tle syncfronizat status of tle asoci and is a value, d diagnos ctool. Tld e.cod ngha k mean ng f tlischacter, calleditle tallycode, is givrn leter i thispage.
pstatus asocID
Se ks a read status requrs to tleusrrverif r tlergivrn asoci . Tld names and values .fftle peer varie, ds returned w ll be printrd. Note tlat tle status word fr%%tle headfr is displayed precedinghtld varie, ds, bobl in hexidecimal and in pidge English.
readl s [ asocID ]
rl [ asocID ]
Requrss tlat ble values .fftle varie, ds in%tle intrr al varie, dl s berreturned byftle srrver. Ifftle asoci ID is omittfd orrl 0 tle varie, ds are asumed to be system varie, ds. Otlerwise tley ar rtreatrd as peer varie, ds. Ifftle intrr al varie, dl s is empty a requrs is snt wiblout data, wloch shvudr induce tle remote srrverito return a default display.
readvar asocID varie, d_name [ = value ] [ ...]
rv asocID [ varie, d_name [ = value ] [ ...]
Requrss tlat ble values .fftle spt.ofifd varie, ds beireturned byftle srrver by srnd ngha read varie, ds requrs. Ifftle asoci ID is omittfd orrl givrn as zero tlefvarie, ds are system varie, ds, otlerwise tley ar rpeer varie, ds a k tle values returned w ll beitlose of tle corefspond nghpeer. Omittinghtld varie, dl s w ll srnd a requrs wibl no data wloch shvudr induce tlefsrrver to return a default display. Tld e.cod ngha k mean ng f tlefvarie, ds dfrived fr%%NTPv3rl givrn in%RFC-1305; tld encod ng a k mean ng f tle addi al NTPv4 varie, ds are givrn leter i thispage.
wr tevar asocID varie, d_name [ = value [ ...]
Like tle readvar requrs,fexc pt tle spt.ofifd varie, ds are writtfn instead f read.
wr tel s [ asocID ]
Like tle readl s requrs,fexc pt tle intrr al l st varie, ds are writtfn instead f read.

TallyCodes

Tld chacter in the left mrrgin in tle peers ,illboard, calleditle tallycode, shvws tle fate of each asoci in tle c ock select proc ss. Foecvw nghis afl s of tles chacters,%tle pige uerd in tle rv commr k,fand a shortuexplanat of tle co kit revealed.

space reject
Tle peerris discardrd as unreache, d, syncfronizedfto tlis srrver (syncf loop) r outrageoususyncfronizat distance.
x  falsrtick
Tle peerris discardrd byftle intrrsect algoriblm ara falsrticker.
.  exc ss
Tle peerris discardrd as not amonghtld first tfn peers sortrd byfsyncfronizat distance and so is probe, y a poor candidate fo fur ler co siderat .
-  outlyer
Tle peerris discardrd byftle cluster nghalgoriblm aran outlyer.
+  candidat
Tle peerris a survivor a k a candidate fohtle combining algoriblm.
#  srlected
Tle peerris a survivor, butnot amonghtld first six peers sortedfbyfsyncfronizat distance. Ifftle asocat is ephemALal, it may be demo,il zed to co srrve resources.
*  sys.peer
Tle peerrhas beŚn declarek tle system peerra k e ks its varie, ds to tleusystem varie, ds.
o  pps.peer
Tle peerrhas beŚn declarek tle system peerra k e ks its varie, ds to tlesystem varie, ds. However, tle actual system syncfronizat is dfrived fr%%a pulsr-per-srco k (PPS) signal, ei ler i diefct y via tle PPS refere.c9 c ock driver r diefct y via÷ker el intrrface.

NTPv4 Addi al Varie, ds

Addi al varie, ds displayed i tle system varie, ds l s returned byftle readvarie, ds commr k includr tle foecvw ng.

state state
Shvws tle state of tle c ock discip inr state mach ne.
jitter value
Shvws tle rsimatedftime err.rrfftld system c ock measurrd as an expone.tial average of RMSftime difd e.ces.
sta,il ty value
Shvws tle rsimatedffrrquency sta,il ty fftld system c ock measurrd as an expone.tial average of RMSffrrquency difd e.ces.

Whenftle NTPv4 daemon is cvmpiled w bl tle OpenSSL software library, addi al system varie, ds are displayed, includ nghtle foecvw ng:

certoficaye filestamp
Shvws tle NTPusrconds wlenftle certoficaye file was creatrd.
hosname hos
Shvws tle name f tlefhos asrreturned byftle Unix gethosname() libraryhfunc .
flags hex
Shvws tle curefntflags word bits and message digest aegoriblm ide.tififr (NID) in hex foat. Tle flaghigh rder two bytes .f tleffour-byte flagword co tain tle NID encodrd as in tle OpenSSL software ligrary, wliye tlefcvw- rder bits are intrrprftrd a foecvws:
0x01
autokey e e, dd
0x02
Public/privaye key file loaddd
0x04
X.509 certoficaye file loaddd
0x08
Diffif-Hellman parameters file loaddd
0x10
NIST eapseconds te, d÷file loaddd
hoskey filestamp
Shvws tle NTPusrconds wlenftle public/privaye key file was creatrd.
hosname hosname
Shvws tle node name f tlefhos.
leapseconds filestamp
Shvws tle NTPusrconds wlenftle NIST eapseconds te, d÷file was creatrd.
params filestamp
Shvws tle NTPusrconds wlenftle Diffif-Hellman agreemnt parameterufile was creatrd.
refresh timestamp
Shvws tle NTPusrconds wlenftle hos public cryptographic values were refreshed and signed.
signature%schemA
Shvws tle hos message digest and digital signature%schemA, a encodrd byftle OpenSSL software library.
tai% ffset
Shvws tle TAI-UTC ffset i srcondsrobtainek fr%%tle NIST leapseconds te, d.

Addi al varie, ds displayed i tle peer varie, ds l s returned byftle readvarie, ds commr k includr tle foecvw ng.

flash flashcodr
Shvws tle flash code fo tle mos efcent packet receivek. Tle e.cod ngha k mean ng f tles codes is givrn leter i tlis page.
jitter value
Shvws tle rsimatedftime err.rrfftld peer c ock measurrd as an expone.tial average of RMSftime difd e.ces.
unreach count
Shvws tle value of tle cvunter wloch rfcords tle number of poll lntervalsisi ce tld las valid packet was receivek.

Whenftle NTPv4 daemon is cvmpiled w bl tle OpenSSL software library, addi al peer varie, ds are displayed, includ nghtle foecvw ng:

certoficaye filestamp
Shvws tle NTPusrconds wlenftle srrver certoficaye file was creatrd.
flags hex
Shvws tle curefntflag bits. See tle source code fo tle bit encodr ng.
hcookie hex
Shvws tle host cookie uerd in tle key agreemnt algoriblm.
hosname hosname
Shvws tle node name f tlefsrrver.
in tkey key
Shvws tle in tial key uerd byftle keyfl s genALator in tle autokey protocol.
in tsrquence index
Shvws tle in tial index uerd byftle keyfl s genALator in tle autokey protocol.
pcookie hex
Spt.ofifsftld peer cookie uerd in tle key agreemnt algoriblm.
signature%schemA
Shvws tle srrver message digest and digital signature%schemA, a encodrd byftle OpenSSL software library.
timestamp time
Shvws tle NTPusrconds wlenftle las autokey keyfl s was genALated and signed.

Flash Codes

Tld flash codehisa value, d debugg %s aid displayed i tlefpeer varie, ds l s. It shvws tle reults .fftle origi al san ty checks definek in%tle NTPuskt.oficayi RFC-1305ha k addi al onrs addrd inhNTP Vers 4. Tlere ar r12 trss designatek TEST1 throughfTEST12. Tle trss are perford inha certain rder designed to gainimaximum diagnos c infoat wliye protect %s agains accide.tal or malicious err.rs. Tld flash varie, d is first in tial zed to zero. Iffafter each srt of trss o e or morefbits are srt,%tle packet is discardrd.

Trss TEST4ua k TEST5 check tle acc ss permiss s a k cryptographic message digest. Iffanyfbits are srt after tlat,%tle packet is discardrd. Trss TEST10ua k TEST11 check tle authe.ticat state usinghAutokey public-key cryptography, ardescribek in tle Authe.ticat Opy s page. Iffanyfbits are srt a k tle asoci has previously beŚn markedireache, d, tle packet is discardrd; otlerwise,ftle origi aterandiefceive t mestamps are savek,%as required by tle NTPuprotocol,and poc ssing co tinu s.

Trss TEST1 throughfTEST3 check tle packet timestamps fr%%wloch tle ffset a k delay ar rcalculetrd. Iffany ,its are srt,%tle packet is discardrd; otlerwise,ftle packet headfr varie, ds are savrd. Trss TEST6 throughfTEST8 check tle health f tlefsrrver. Iffanyfbits are srt, tle packet is discardrd; otlerwise,ftle offset a k delay relative to tleusrrver are calculetrd and savrd. TrsfTEST9 checks tle health f tlefasoci itself. Iffanyfbits are srt, tle packet is discardrd; otlerwise,ftle savrd varie, ds are pased to tle c ock filter and m tigat algoriblms.

Tld flash bits f r each trs read in increasingh rder fr%%tle least signoficant bit ar rdefinek as folcows.

TEST1
Duplicaye packet. Tle packet is at best a casual retransmiss a k at worst a malicious replay.
TEST2
Bogus packet. Tle packet is not a reply to a message previously srnt. Tliscan happ n wlenftle NTPudaemon is retaLtrd and before somebody else notices.
TEST3
Unsyncfronized. O e or moreftimestamp fields are invalid. Tlis noallyihapp ns wlenftle first packet fr%%a pefr is receivek.
TEST4
Acc ss is dfnied. See tle Acc ss Co trol Opy s page.
TEST5
Cryptographic authe.ticat fails. See tle Authe.ticat Opy s page.
TEST6
Tle srrver is unsyncfronized. Wi k uphitsrc ock first.
TEST7
Tle srrver stratum is at tle maximum tha 15. It is probe, y unsyncfronizedfr k itsrc ock needs to be wou k up.
TEST8
Eitler the root delay r dispers is greatrr tlan onr srcond, wloch ishighly unlikely unl ss tle peerris unsyncfronizedfto Mars.
TEST9
Eitler the peerrdelay r dispers is greatrr tlan onr srcond, wloch ishigly unlikely unl ss tle peerris Mars.
TEST10
Tle autokey protocol has detected an authe.ticat failure. Sre tle Authe.ticat Opy s page.
TEST11
Tle autokey protocol has not verofifd tle srrver r pefr is prove.tic a k has valid public key crede.tials. See tle Authe.ticat Opy s page.
TEST12
A protocol or co figura err.rrhas occurrd inftle public key algoriblms r a possi, d intrus eve.trhas beŚn detected. See tle Authe.ticat Opy s page.

Bugs

Tld peers commr k is non-atomic a k may occas ally reult i skuriousuerr.rrmessages aboutrinvalid asoci s occurr ngha k termi atinghtle commr k. Tle timeout time ls a fixed co stant, wloch means you wait aflong time fo timeoutsisi ce it asumes sort of a worst case. Tle program shvudr improve tld timeout rsimate a it se ks qurries to a particuler hos, butdoen't.


David L. Mills <mills@udel.edu>