diff options
Diffstat (limited to 'contrib/ntp/html/ntpq.htm')
| -rw-r--r-- | contrib/ntp/html/ntpq.htm | 747 |
1 files changed, 747 insertions, 0 deletions
diff --git a/contrib/ntp/html/ntpq.htm b/contrib/ntp/html/ntpq.htm new file mode 100644 index 0000000..9308867 --- /dev/null +++ b/contrib/ntp/html/ntpq.htm @@ -0,0 +1,747 @@ +<HTML> +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META NAME="GENERATOR" CONTENT="Mozilla/4.01 [en] (Win95; I) [Netscape]"> + <TITLE>ntpq - standard NTP query program +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>pq</TT> - standard NTP query program</H3> + +<HR> +<H4> +Synopsis</H4> +<TT>ntpq [-inp] [-c <I>command</I>] [<I>host</I>] [...]</TT> +<H4> +Description</H4> +<TT>ntpq</TT> is used to query NTP servers which implement the recommended +NTP mode 6 control message format about current state and to request changes +in that state. The program may 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. +<TT>ntpq</TT> can also obtain and print a list of peers in a common format +by sending multiple queries to the server. + +<P>If one or more request options is included on the command line when +<TT>ntpq</TT> 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, <TT>ntpq</TT> +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. <TT>ntpq</TT> +will prompt for commands if the standard input is a terminal device. + +<P><TT>ntpq</TT> uses NTP mode 6 packets to communicate with the NTP server, +and hence can be used to query any compatable 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. <TT>ntpq</TT> makes one attempt to retransmit requests, and will +time requests out if the remote host is not heard from within a suitable +timeout time. + +<P>Command line options are described following. Specifying a command line +option other than -i or -n will cause the specified query (queries) to +be sent to the indicated host(s) immediately. Otherwise, <TT>ntpq</TT> +will attempt to read interactive format commands from the standard input. +<DL> +<DT> +<TT>-c</TT></DT> + +<DD> +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 -c options may be given.</DD> + +<DT> +<TT>-i</TT></DT> + +<DD> +Force <TT>ntpq</TT> to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input.</DD> + +<DT> +<TT>-n</TT></DT> + +<DD> +Output all host addresses in dotted-quad numeric format rather than converting +to the canonical host names.</DD> + +<DT> +<TT>-p</TT></DT> + +<DD> +Print a list of the peers known to the server as well as a summary of their +state. This is equivalent to the <TT>peers</TT> interactive command.</DD> +</DL> + +<H4> +Internal Commands</H4> +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 "<", followed by a file name, to the +command line. A number of interactive format commands are executed entirely +within the <TT>ntpq</TT> program itself and do not result in NTP mode 6 +requests being sent to a server. These are described following. +<DL> +<DT> +<TT>? [<I>command_keyword</I>]</TT></DT> + +<BR><TT>helpl [ <I>command_keyword</I> ]</TT> +<DD> +A <TT>"?"</TT> by itself will print a list of all the command keywords +known to this incarnation of <TT>ntpq</TT>. A <TT>"?"</TT> followed by +a command keyword will print funcation and usage information about the +command. This command is probably a better source of information about +<TT>ntpq</TT> than this manual page.</DD> + +<DD> + </DD> + +<DT> +<TT>addvars <I>variable_name</I> [ = <I>value</I>] [...]</TT></DT> + +<BR><TT>rmvars <I>variable_name</I> [...]</TT> +<BR><TT>clearvars</TT> +<DD> +The data carried by NTP mode 6 messages consists of a list of items of +the form <TT><I>variable_name</I> = <I>value</I></TT>, where the <TT>" += <I>value</I>"</TT> is ignored, and can be omitted, in requests to the +server to read variables. <TT>ntpq</TT> maintains an internal list in which +data to be included in control messages can be assembled, and sent using +the readlist and writelist commands described below. The 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 rmvars command can be used to remove individual +variables from the list, while the clearlist command removes all variables +from the list.</DD> + +<DD> + </DD> + +<DT> +<TT>authenticate yes | no</TT></DT> + +<DD> +Normally <TT>ntpq</TT> does not authenticate requests unless they are write +requests. The command authenticate yes causes <TT>ntpq</TT> to send authentication +with all requests it makes. Authenticated requests causes some servers +to handle requests slightly differently, and can occasionally melt the +CPU in fuzzballs if you turn authentication on before doing a peer display.</DD> + +<DD> + </DD> + +<DT> +<TT>cooked</TT></DT> + +<DD> +Causes output from query commands to be <TT>"cooked"</TT>. Variables which +are recognized by the server will have their values reformatted for human +consumption. Variables which <TT>ntpq</TT> thinks should have a decodeable +value but didn't are marked with a trailing <TT>"?"</TT>.</DD> + +<DD> + </DD> + +<DT> +<TT>debug more | less | off</TT></DT> + +<DD> +Turns internal query program debugging on and off.</DD> + +<DD> + </DD> + +<DT> +<TT>delay <I>milliseconds</I></TT></DT> + +<DD> +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.</DD> + +<DD> + </DD> + +<DT> +<TT>host <I>hostname</I></TT></DT> + +<DD> +Set the host to which future queries will be sent. Hostname may be either +a host name or a numeric address.</DD> + +<DD> + </DD> + +<DT> +<TT>hostnames [yes | no]</TT></DT> + +<DD> +If <TT>"yes"</TT> is specified, host names are printed in information displays. +If <TT>"no"</TT> is specified, numeric addresses are printed instead. The +default is <TT>"yes"</TT>, unless modified using the command line <TT>-n</TT> +switch.</DD> + +<DD> + </DD> + +<DT> +<TT>keyid <I>keyid</I></TT></DT> + +<DD> +This command allows the specification of a 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.</DD> + +<DD> + </DD> + +<DT> +<TT>ntpversion 1 | 2 | 3 | 4</TT></DT> + +<DD> +Sets the NTP version number which <TT>ntpq</TT> claims in packets. Defaults +to 3, Note that mode 6 control messages (and modes, for that matter) didn't +exist in NTP version 1. There appear to be no servers left which demand +version 1.</DD> + +<DD> + </DD> + +<DT> +<TT>quit</TT></DT> + +<DD> +Exit <TT>ntpq</TT>.</DD> + +<DD> + </DD> + +<DT> +<TT>passwd</TT></DT> + +<DD> +This command prompts you to type in a password (which will not be echoed) +which will be used to authenticate configuration requests. The password +must correspond to the key configured for use by the NTP server for this +purpose if such requests are to be successful.</DD> + +<DD> + </DD> + +<DT> +<TT>raw</TT></DT> + +<DD> +Causes all output from query commands is printed as received from the remote +server. The only formating/intepretation done on the data is to transform +nonascii data into a printable (but barely understandable) form.</DD> + +<DD> + </DD> + +<DT> +<TT>timeout <I>millseconds</I></TT></DT> + +<DD> +Specify a timeout period for responses to server queries. The default is +about 5000 milliseconds. Note that since <TT>ntpq</TT> retries each query +once after a timeout, the total waiting time for a timeout will be twice +the timeout value set.</DD> +</DL> + +<H4> +Control Message Commands</H4> +Each peer known to an NTP server has a 16 bit integer association identifier +assigned to it. 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. + +<P>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. +<DL> +<DT> +<TT>associations</TT></DT> + +<DD> +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 <TT>condition</TT> field. Note that the data returned +by the <TT>"associations"</TT> command is cached internally in <TT>ntpq</TT>. +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.</DD> + +<DD> + </DD> + +<DT> +<TT>clockvar [<I>assocID</I>] [<I>variable_name</I> [ = <I>value</I> [...] +] [...]</TT></DT> + +<DT> +<TT>cv [<I>assocID</I>] [<I>variable_name</I> [ = <I>value</I> [...] ] +[...]</TT></DT> + +<DD> +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 <TT>"system clock"</TT> 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.</DD> + +<DD> + </DD> + +<DT> +<TT>lassocations</TT></DT> + +<DD> +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 <TT>"associations"</TT> 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 <TT>"associations"</TT> +command is used, but are included in the output of <TT>"lassociations"</TT>.</DD> + +<DD> + </DD> + +<DT> +<TT>lpassociations</TT></DT> + +<DD> +Print data for all associations, including out-of-spec client associations, +from the internally cached list of associations. This command differs from +<TT>"passociations"</TT> only when dealing with fuzzballs.</DD> + +<DD> + </DD> + +<DT> +<TT>lpeers</TT></DT> + +<DD> +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.</DD> + +<DD> + </DD> + +<DT> +<TT>mreadlist <I>assocID</I> <I>assocID</I></TT></DT> + +<BR><TT>mrl <I>assocID</I> <I>assocID</I></TT> +<DD> +Like the <TT>readlist</TT> 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 <TT>associations</TT> command.</DD> + +<DD> + </DD> + +<DT> +<TT>mreadvar <I>assocID</I> <I>assocID</I> [ <I>variable_name</I> [ = <I>value</I> +[ ... ]</TT></DT> + +<BR><TT>mrv <I>assocID</I> <I>assocID</I> [ <I>variable_name</I> [ = <I>value</I> +[ ... ]</TT> +<DD> +Like the <TT>readvar</TT> 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 <TT>associations</TT> command.</DD> + +<DD> + </DD> + +<DT> +<TT>opeers</TT></DT> + +<DD> +An old form of the <TT>peers</TT> command with the reference ID replaced +by the local interface address.</DD> + +<DD> + </DD> + +<DT> +<TT>passociations</TT></DT> + +<DD> +Prints association data concerning in-spec peers from the internally cached +list of associations. This command performs identically to the <TT>"associations"</TT> +except that it displays the internally stored data rather than making a +new query.</DD> + +<DD> + </DD> + +<DT> +<TT>peers</TT></DT> + +<DD> +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.</DD> + +<DD> + </DD> + +<DD> +The character in the left margin indicates the fate of this peer in the +clock selection process. Folowing is a list of these characters, the pidgeon +used in the <TT>rv</TT> command, and a short explanation of the condition +revealed.</DD> + +<DD> + </DD> + +<DD> +<TT>space reject</TT></DD> + +<DL> +<DD> +The peer is discarded as unreachable, synchronized to this server (synch +loop) or outrageous synchronization distance.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>x falsetick</TT></DD> + +<DL> +<DD> +The peer is discarded by the intersection algorithm as a falseticker.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>. excess</TT></DD> + +<DL> +<DD> +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.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>- outlyer</TT></DD> + +<DL> +<DD> +The peer is discarded by the clustering algorithm as an outlyer.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>+ candidat</TT></DD> + +<DL> +<DD> +The peer is a survivor and a candidate for the combining algorithm.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT># selected</TT></DD> + +<DL> +<DD> +The peer is a survivor, but not among the first six peers sorted by synchronization +distance. If the assocation is ephemeral, it may be demobilized to conserve +resources.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>* sys.peer</TT></DD> + +<DL> +<DD> +The peer has been declared the system peer and lends its variables to the +system variables.</DD> +</DL> + +<DD> +<TT> </TT></DD> + +<DD> +<TT>o pps.peer</TT></DD> + +<DL> +<DD> +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.</DD> + +<DD> + </DD> +</DL> + +<DD> +The <TT>flash</TT> variable is not defined in the NTP specification, but +is included as a valuable debugging aid. It displays the results of the +packet sanity checks defined in the NTP specification <TT>TEST1</TT> through +<TT>TEST9</TT>. The bits for each test read in increasing sequency from +the least significant bit and are defined as follows.</DD> + +<DD> + </DD> + +<DD> +The following <TT>TEST1</TT> through <TT>TEST4</TT> enumerate procedure +errors. The packet timestamps may or may not be believed, but the remaining +header data are ignored.</DD> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST1</TT></DD> + +<DL> +<DD> +Duplicate packet. A copy from somewhere.</DD> +</DL> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST2</TT></DD> + +<DL> +<DD> +Bogus packet. It is not a reply to a message previously sent. This can +happen when the NTP daemon is restarted and before a peer notices.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST3</TT></DD> + +<DL> +<DD> +Unsynchronized. One or more timestamp fields are missing. This normally +happens when the first packet from a peer is received.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST4</TT></DD> + +<DL> +<DD> +Either peer delay or peer dispersion is greater than one second. Ya gotta +be kidding.</DD> + +<DD> + </DD> +</DL> + +<DD> +The following <TT>TEST5</TT> through <TT>TEST10</TT> ennumerate errors +in the packet header. The packet is discarded without inspecting its contents.</DD> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST5</TT></DD> + +<DL> +<DD> +Cryptographic authentication fails. See the <A HREF="authopt.htm">Authentication +Options</A> page.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST6</TT></DD> + +<DL> +<DD> +Peer is unsynchronized. Wind up its clock first.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST7</TT></DD> + +<DL> +<DD> +Peer stratum is greater than 15. The peer is probably unsynchronized.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST8</TT></DD> + +<DL> +<DD> +Either root delay or root dispersion is greater than one second. Too far +from home.</DD> +</DL> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST9</TT></DD> + +<DL> +<DD> +Peer cryptographic authentication fails. Either the key identifier or key +is wrong or somebody trashed our packet.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST10</TT></DD> + +<DL> +<DD> +Access is denied. See the <A HREF="accopt.htm">Access Control Options</A> +page.</DD> + +<DD> + </DD> +</DL> + +<DT> +<TT>pstatus <I>assocID</I></TT></DT> + +<DD> +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 hexidecimal and in pidgeon English.</DD> + +<DD> + </DD> + +<DT> +<TT>readlist [ <I>assocID</I> ]</TT></DT> + +<BR><TT>rl [ <I>assocID</I> ]</TT> +<DD> +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.</DD> + +<DD> + </DD> + +<DT> +<TT>readvar <I>assocID</I> <I>variable_name</I> [ = <I>value</I> ] [ ... +]</TT></DT> + +<BR><TT>rv <I>assocID</I> [ <I>variable_name</I> [ = <I>value</I> ] [ ... +]</TT> +<DD> +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.</DD> + +<DD> + </DD> + +<DT> +<TT>writevar <I>assocID</I> <I>variable_name</I> [ = <I>value</I> [ ... +]</TT></DT> + +<DD> +Like the readvar request, except the specified variables are written instead +of read.</DD> + +<DD> + </DD> + +<DT> +<TT>writelist [ <I>assocID</I> ]</TT></DT> + +<DD> +Like the readlist request, except the internal list variables are written +instead of read.</DD> +</DL> + +<H4> +Bugs</H4> +The 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 doesn't. +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> |
