diff options
Diffstat (limited to 'usr.sbin/ntp/doc/ntpq.8')
| -rw-r--r-- | usr.sbin/ntp/doc/ntpq.8 | 851 |
1 files changed, 851 insertions, 0 deletions
diff --git a/usr.sbin/ntp/doc/ntpq.8 b/usr.sbin/ntp/doc/ntpq.8 new file mode 100644 index 0000000..0a47c76 --- /dev/null +++ b/usr.sbin/ntp/doc/ntpq.8 @@ -0,0 +1,851 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd May 17, 2006 +.Dt NTPQ 8 +.Os +.Sh NAME +.Nm ntpq +.Nd standard NTP query program +.Sh SYNOPSIS +.Nm +.Op Fl inp +.Op Fl c Ar command +.Op Ar host +.Op Ar ... +.Sh DESCRIPTION +The +.Nm +utility is used to monitor NTP daemon +.Xr ntpd 8 +operations and determine performance. +It uses the standard NTP mode 6 control message formats +defined in Appendix B of the NTPv3 specification RFC1305. +The same formats are used in NTPv4, although some of the variables +have changed and new ones added. +The description on this page is for the NTPv4 variables. +.Pp +The program can be run either in interactive mode or controlled +using command line arguments. +Requests to read and write arbitrary variables can be assembled, +with raw and pretty-printed output options being available. +The +.Nm +can also obtain and print a list of peers in a common format +by sendingmultiple queries to the server. +.Pp +If one or more request options is included on the command line +when +.Nm +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.Nm +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.Nm +utility will prompt for +commands if the standard input is a terminal device. +.Pp +The +.Nm +utility uses NTP mode 6 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.Nm +utility makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +.Pp +For examples and usage, see the +.Qq NTP Debugging Techniques +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) . +.Pp +The following options are available: +.Bl -tag -width indent +.It Fl 4 +Force DNS resolution of following host names on the command line to the +IPv4 namespace. +.It Fl 6 +Force DNS resolution of following host names on the command line to the +IPv6 namespace. +.It Fl c +The following argument is interpreted as an interactive format +command and is added to the list of commands to be executed on the +specified host(s). +Multiple +.Fl c +options may be given. +.It Fl d +Turn on debugging mode. +.It Fl i +Force +.Nm +to operate in interactive mode. +Prompts +will be written to the standard output and commands read from the +standard input. +.It Fl n +Output all host addresses in dotted-quad numeric format rather +than converting to the canonical host names. +.It Fl p +Print a list of the peers known to the server as well as a +summary of their state. +This is equivalent to the +.Ic peers +interactive command. +.El +.Pp +Note that in contexts where a host name is expected, a +.Fl 4 +qualifier preceding the host name forces DNS resolution to the +IPv4 namespace, while a +.Fl 6 +qualifier forces DNS resolution to the IPv6 namespace. +Specifying a +command line option other than +.Fl i +or +.Fl n +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +.Nm +will attempt to read +interactive format commands from the standard input. +.Ss "Internal Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. +The output of a +command is normally sent to the standard output, but optionally the +output of individual commands may be sent to a file by appending a +.Ql \&> , +followed by a file name, to the command line. +A +number of interactive format commands are executed entirely within +the +.Nm +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +.Bl -tag -width indent +.It Ic \&? Op Ar command_keyword +.It Ic help Op Ar command_keyword +A +.Sq Ic \&? +by itself will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Sq Ic \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Nm +than this manual +page. +.It Xo Ic addvars +.Ar variable_name Ns Op = Ns Ar value ... +.Xc +.It Ic rmvars Ar variable_name ... +.It Ic clearvars +The data carried by NTP mode 6 messages consists of a list of +items of the form +.Ql variable_name=value , +where the +.Ql =value +is ignored, and can be omitted, +in requests to the server to read variables. +The +.Nm +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +.Ic readlist +and +.Ic writelist +commands described below. +The +.Ic addvars +command allows variables and their optional values to be added to +the list. +If more than one variable is to be added, the list should +be comma-separated and not contain white space. +The +.Ic rmvars +command can be used to remove individual variables from the list, +while the +.Ic clearlist +command removes all variables from the +list. +.It Ic cooked +Causes output from query commands to be "cooked", so that +variables which are recognized by +.Nm +will have their +values reformatted for human consumption. +Variables which +.Nm +thinks should have a decodable value but did not are +marked with a trailing +.Ql \&? . +.It Xo Ic debug +.Cm more | +.Cm less | +.Cm off +.Xc +Turns internal query program debugging on and off. +.It Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.It Ic host Ar hostname +Set the host to which future queries will be sent. +Hostname may +be either a host name or a numeric address. +.It Ic hostnames Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +.Fl n +switch. +.It Ic keyid Ar keyid +This command specifies the key number to be used to authenticate +configuration requests. +This must correspond to a key number the server has +been configured to use for this purpose. +.It Xo Ic ntpversion +.Cm 1 | +.Cm 2 | +.Cm 3 | +.Cm 4 +.Xc +Sets the NTP version number which +.Nm +claims in +packets. +Defaults to 3, Note that mode 6 control messages (and +modes, for that matter) did not exist in NTP version 1. +There appear +to be no servers left which demand version 1. +.It Ic passwd +This command prompts for a password (which will not be echoed) which will +be used to authenticate configuration requests. +The password must +correspond to the key configured for NTP server for this purpose. +.It Ic quit +Exit +.Nm . +.It Ic raw +Causes all output from query commands is printed as received +from the remote server. +The only formatting/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.El +.Ss Control Message Commands +Each association known to an NTP server has a 16 bit integer association +identifier. +NTP control messages which carry peer variables must identify the +peer the values correspond to by including its association ID. +An association +ID of 0 is special, and indicates the variables are system variables, whose +names are drawn from a separate name space. +.Pp +Control message commands result in one or more NTP mode 6 +messages being sent to the server, and cause the data returned to +be printed in some format. +Most commands currently implemented send +a single message and expect a single response. +The current +exceptions are the peers command, which will send a preprogrammed +series of messages to obtain the data it needs, and the mreadlist +and mreadvar commands, which will iterate over a range of +associations. +.Bl -tag -width indent +.It Ic associations +Obtains and prints a list of association identifiers and peer +statuses for in-spec peers of the server being queried. +The list is +printed in columns. +The first of these is an index numbering the +associations from 1 for internal use, the second the actual +association identifier returned by the server and the third the +status word for the peer. +This is followed by a number of columns +containing data decoded from the status word. +See the peers command +for a decode of the +.Sq condition +field. +Note that the data +returned by the +.Ic associations +command is cached internally +in +.Nm . +The index is then of use when dealing with stupid +servers which use association identifiers which are hard for humans +to type, in that for any subsequent commands which require an +association identifier as an argument, the form and index may be +used as an alternative. +.It Xo Ic clockvar Op Ar assocID +.Oo +.Ar variable_name Ns Op = Ns Ar value ... +.Oc +.Ar ... +.Xc +.It Xo Ic cv Op Ar assocID +.Oo +.Ar variable_name Ns Op = Ns Ar value ... +.Oc +.Ar ... +.Xc +Requests that a list of the server's clock variables be sent. +Servers which have a radio clock or other external synchronization +will respond positively to this. +If the association identifier is +omitted or zero the request is for the variables of the +.Sq system clock +and will generally get a positive response from all +servers with a clock. +If the server treats clocks as pseudo-peers, +and hence can possibly have more than one clock connected at once, +referencing the appropriate peer association ID will show the +variables of a particular clock. +Omitting the variable list will +cause the server to return a default variable display. +.It Ic lassociations +Obtains and prints a list of association identifiers and peer +statuses for all associations for which the server is maintaining +state. +This command differs from the +.Ic associations +command +only for servers which retain state for out-of-spec client +associations (i.e., fuzzballs). +Such associations are normally +omitted from the display when the +.Ic associations +command is +used, but are included in the output of +.Ic lassociations . +.It Ic lpassociations +Print data for all associations, including out-of-spec client +associations, from the internally cached list of associations. +This +command differs from +.Ic passociations +only when dealing with +fuzzballs. +.It Ic lpeers +Like R peers, except a summary of all associations for which +the server is maintaining state is printed. +This can produce a much +longer list of peers from fuzzball servers. +.It Ic mreadlist Ar assocID Ar assocID +.It Ic mrl Ar assocID Ar assocID +Like the +.Ic readlist +command, except the query is done +for each of a range of (nonzero) association IDs. +This range is +determined from the association list cached by the most recent +.Ic associations +command. +.It Xo Ic mreadvar Ar assocID Ar assocID +.Oo +.Ar variable_name Ns Op = Ns Ar value ... +.Oc +.Xc +.It Xo Ic mrv Ar assocID Ar assocID +.Oo +.Ar variable_name Ns Op = Ns Ar value ... +.Oc +.Xc +Like the +.Ic readvar +command, except the query is done for +each of a range of (nonzero) association IDs. +This range is +determined from the association list cached by the most recent +.Ic associations +command. +.It Ic opeers +An old form of the +.Ic peers +command with the reference ID +replaced by the local interface address. +.It Ic passociations +Displays association data concerning in-spec peers from the +internally cached list of associations. +This command performs +identically to the +.Ic associations +except that it displays +the internally stored data rather than making a new query. +.It Ic peers +Obtains a current list peers of the server, along with a +summary of each peer's state. +Summary information includes the +address of the remote peer, the reference ID (0.0.0.0 if this is +unknown), the stratum of the remote peer, the type of the peer +(local, unicast, multicast or broadcast), when the last packet was +received, the polling interval, in seconds, the reachability +register, in octal, and the current estimated delay, +offset and dispersion of the peer, all in milliseconds. +The character at the left margin of each line shows the +synchronization status of the association and is a valuable +diagnostic tool. +The encoding and meaning of this character, +called the tally code, is given later in this page. +.It Ic pstatus Ar assocID +Sends a read status request to the server for the given +association. +The names and values of the peer variables returned +will be printed. +Note that the status word from the header is +displayed preceding the variables, both in hexadecimal and in +pidgeon English. +.It Ic readlist Ar assocID +.It Ic rl Ar assocID +Requests that the values of the variables in the internal +variable list be returned by the server. +If the association ID is +omitted or is 0 the variables are assumed to be system variables. +Otherwise they are treated as peer variables. +If the internal +variable list is empty a request is sent without data, which should +induce the remote server to return a default display. +.It Xo Ic readvar Ar assocID +.Ar variable_name Ns Op = Ns Ar value +.Ar ... +.Xc +.It Xo Ic rv Ar assocID +.Ar variable_name Ns Op = Ns Ar value +.Ar ... +.Xc +Requests that the values of the specified variables be returned +by the server by sending a read variables request. +If the +association ID is omitted or is given as zero the variables are +system variables, otherwise they are peer variables and the values +returned will be those of the corresponding peer. +Omitting the +variable list will send a request with no data which should induce +the server to return a default display. +The +encoding and meaning of the variables derived from NTPv3 is given in +RFC-1305; the encoding and meaning of the additional NTPv4 variables are +given later in this page. +.It Xo Ic writevar Ar assocID +.Ar variable_name Ns Op = Ns Ar value +.Ar ... +.Xc +Like the readvar request, except the specified variables are +written instead of read. +.It Ic writelist Op Ar assocID +Like the readlist request, except the internal list variables +are written instead of read. +.El +.Ss Tally Codes +The character in the left margin in the +.Sq peers +billboard, +called the tally code, shows the fate of each association +in the clock selection process. +Following is a list of these characters, the pigeon used +in the +.Ic rv +command, and a short explanation of the condition revealed. +.Bl -tag -width indent +.It space +.Pq reject +The peer is discarded as unreachable, synchronized to this server (synch +loop) or outrageous synchronization distance. +.It x +.Pq falsetick +The peer is discarded by the intersection algorithm as a falseticker. +.It \&. +.Pq excess +The peer is discarded as not among the first ten peers sorted by +synchronization distance and so is probably a poor candidate for further +consideration. +.It \&- +.Pq outlyer +The peer is discarded by the clustering algorithm as an outlyer. +.It \&+ +.Pq candidat +The peer is a survivor and a candidate for the combining algorithm. +.It \&# +.Pq selected +The peer is a survivor, but not among the first six peers sorted by +synchronization distance. +If the association is ephemeral, it may be +demobilized to conserve resources. +.It \&* +.Pq sys.peer +The peer has been declared the system peer and lends its variables to the +system variables. +.It o +.Pq pps.peer +The peer has been declared the system peer and lends its variables to +the system variables. +However, the actual system synchronization is derived +from a pulse-per-second (PPS) signal, either indirectly via the PPS +reference clock driver or directly via kernel interface. +.El +.Ss System Variables +The +.Cm status , +.Cm leap , +.Cm stratum , +.Cm precision , +.Cm rootdelay , +.Cm rootdispersion , +.Cm refid , +.Cm reftime , +.Cm poll , +.Cm offset , +and +.Cm frequency +variables are described in RFC-1305 +specification. +Additional NTPv4 system variables include the following. +.Bl -tag -width indent +.It version +Everything you might need to know about the software version and generation +time. +.It processor +The processor and kernel identification string. +.It system +The operating system version and release identifier. +.It state +The state of the clock discipline state machine. +The values are described +in the architecture briefing on the NTP Project page linked from +www.ntp.org. +.It peer +The internal integer used to identify the association currently designated +the system peer. +.It jitter +The estimated time error of the system clock measured as an exponential +average of RMS time differences. +.It stability +The estimated frequency stability of the system clock measured as an +exponential average of RMS frequency differences. +.El +.Pp +When the NTPv4 daemon is compiled with the OpenSSL software library, additional +system variables are displayed, including some or all of the following, +depending on the particular dance: +.Bl -tag -width indent +.It flags +The current flags word bits and message digest algorithm identifier (NID) +in hex format. +The high order 16 bits of the four-byte word contain the NID +from the OpenSSL ligrary, while the low-order bits are interpreted as +follows: +.Bl -tag -width indent +.It 0x01 +autokey enabled +.It 0x02 +NIST leapseconds file loaded +.It 0x10 +PC identity scheme +.It 0x20 +IFF identity scheme +.It 0x40 +GQ identity scheme +.El +.It hostname +The name of the host as returned by the Unix +.Fn gethostname +library +function. +.It hostkey +The NTP filestamp of the host key file. +.It cert +A list of certificates held by the host. +Each entry includes the subject, +issuer, flags and NTP filestamp in order. +The bits are interpreted as +follows: +.Bl -tag -width indent +.It 0x01 +certificate has been signed by the server +.It 0x02 +certificate is trusted +.It 0x04 +certificate is private +.It 0x08 +certificate contains errors and should not be trusted +.El +.It leapseconds +The NTP filestamp of the NIST leapseconds file. +.It refresh +The NTP timestamp when the host public cryptographic values were refreshed +and signed. +.It signature +The host digest/signature scheme name from the OpenSSL library. +.It tai +The TAI-UTC offset in seconds obtained from the NIST leapseconds table. +.El +.Ss Peer Variables +The +.Cm status , +.Cm srcadr , +.Cm srcport , +.Cm dstadr , +.Cm dstport , +.Cm leap , +.Cm stratum , +.Cm precision , +.Cm rootdelay , +.Cm rootdispersion , +.Cm readh , +.Cm hmode , +.Cm pmode , +.Cm hpoll , +.Cm ppoll , +.Cm offset , +.Cm delay , +.Cm dspersion , +.Cm reftime +variables are described in the RFC-1305 specification, as +are the timestamps +.Cm org , +.Cm rec +and +.Cm xmt . +Additional NTPv4 system variables include +the following. +.Bl -tag -width indent +.It flash +The flash code for the most recent packet received. +The encoding and +meaning of these codes is given later in this page. +.It jitter +The estimated time error of the peer clock measured as an exponential +average of RMS time differences. +.It unreach +The value of the counter which records the number of poll intervals since +the last valid packet was received. +.El +.Pp +When the NTPv4 daemon is compiled with the OpenSSL software library, additional +peer variables are displayed, including the following: +.Bl -tag -width indent +.It flags +The current flag bits. +This word is the server host status word with +additional bits used by the Autokey state machine. +See the source code for +the bit encoding. +.It hostname +The server host name. +.It initkey Ar key +The initial key used by the key list generator in the Autokey protocol. +.It initsequence Ar index +The initial index used by the key list generator in the Autokey protocol. +.It signature +The server message digest/signature scheme name from the OpenSSL software +library. +.It timestamp Ar time +The NTP timestamp when the last Autokey key list was generated and signed. +.El +.Ss Flash Codes +The +.Cm flash +code is a valuable debugging aid displayed in the peer variables +list. +It shows the results of the original sanity checks defined in the NTP +specification RFC-1305 and additional ones added in NTPv4. +There are 12 tests +designated +.Sy TEST1 +through +.Sy TEST12 . +The tests are performed in a certain order +designed to gain maximum diagnostic information while protecting against +accidental or malicious errors. +The +.Sy flash +variable is initialized to zero as +each packet is received. +If after each set of tests one or more bits are set, +the packet is discarded. +.Pp +Tests +.Sy TEST1 +through +.Sy TEST3 +check the packet timestamps from which the offset and +delay are calculated. +If any bits are set, the packet is discarded; otherwise, +the packet header variables are saved. +.Sy TEST4 +and +.Sy TEST5 +are associated with +access control and cryptographic authentication. +If any bits are set, the +packet is discarded immediately with nothing changed. +.Pp +Tests +.Sy TEST6 +through +.Sy TEST8 +check the health of the server. +If any bits are set, +the packet is discarded; otherwise, the offset and delay relative to the server +are calculated and saved. +TEST9 checks the health of the association itself. +If +any bits are set, the packet is discarded; otherwise, the saved variables are +passed to the clock filter and mitigation algorithms. +.Pp +Tests +.Sy TEST10 +through +.Sy TEST12 +check the authentication state using Autokey +public-key cryptography, as described in the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +If +any bits are set and the association has previously been marked reachable, the +packet is discarded; otherwise, the originate and receive timestamps are saved, +as required by the NTP protocol, and processing continues. +.Pp +The +.Cm flash +bits for each test are defined as follows. +.Bl -tag -width indent +.It 0x001 +.Pq TEST1 +Duplicate packet. +The packet is at best a casual retransmission and at +worst a malicious replay. +.It 0x002 +.Pq TEST2 +Bogus packet. +The packet is not a reply to a message previously sent. +This +can happen when the NTP daemon is restarted and before somebody else +notices. +.It 0x004 +.Pq TEST3 +Unsynchronized. +One or more timestamp fields are invalid. +This normally +happens when the first packet from a peer is received. +.It 0x008 +.Pq TEST4 +Access is denied. +See the +.Sx Access Control Support +section of +.Xr ntp.conf 5 . +.It 0x010 +.Pq TEST5 +Cryptographic authentication fails. +See the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +.It 0x020 +.Pq TEST6 +The server is unsynchronized. +Wind up its clock first. +.It 0x040 +.Pq TEST7 +The server stratum is at the maximum than 15. +It is probably unsynchronized +and its clock needs to be wound up. +.It 0x080 +.Pq TEST8 +Either the root delay or dispersion is greater than one second, which is +highly unlikely unless the peer is unsynchronized to Mars. +.It 0x100 +.Pq TEST9 +Either the peer delay or dispersion is greater than one second, which is +higly unlikely unless the peer is on Mars. +.It 0x200 +.Pq TEST10 +The autokey protocol has detected an authentication failure. +See the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +.It 0x400 +.Pq TEST11 +The autokey protocol has not verified the server or peer is proventic and +has valid public key credentials. +See the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +.It 0x800 +.Pq TEST12 +A protocol or configuration error has occurred in the public key algorithms +or a possible intrusion event has been detected. +See the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +.El +.Sh SEE ALSO +.Xr ntp.conf 5 , +.Xr ntpd 8 , +.Xr ntpdc 8 +.Sh BUGS +The +.Ic peers +command is non-atomic and may occasionally result in +spurious error messages about invalid associations occurring and +terminating the command. +The timeout time is a fixed constant, +which means you wait a long time for timeouts since it assumes sort +of a worst case. +The program should improve the timeout estimate as +it sends queries to a particular host, but does not. |
