diff options
Diffstat (limited to 'usr.sbin/xntpd/doc/ntpq.8')
| -rw-r--r-- | usr.sbin/xntpd/doc/ntpq.8 | 566 |
1 files changed, 566 insertions, 0 deletions
diff --git a/usr.sbin/xntpd/doc/ntpq.8 b/usr.sbin/xntpd/doc/ntpq.8 new file mode 100644 index 0000000..81aca09 --- /dev/null +++ b/usr.sbin/xntpd/doc/ntpq.8 @@ -0,0 +1,566 @@ +''' $Header +''' +.de Sh +.br +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp +.if t .sp .5v +.if n .sp +.. +.de Ip +.br +.ie \\n.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +''' +''' Set up \*(-- to give an unbreakable dash; +''' string Tr holds user defined translation string. +''' Bell System Logo is used as a dummy character. +''' +.tr \(bs-|\(bv\*(Tr +.ie n \{\ +.ds -- \(bs- +.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch +.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch +.ds L" "" +.ds R" "" +.ds L' ' +.ds R' ' +'br\} +.el\{\ +.ds -- \(em\| +.tr \*(Tr +.ds L" `` +.ds R" '' +.ds L' ` +.ds R' ' +'br\} +.TH NTPQ 8 LOCAL +.SH NAME +ntpq - standard Network Time Protocol query program +.SH SYNOPSIS +.B ntpq +[ +.B -inp +] [ +.B -c +.I command +] [ +.I host +] [ +.I ... +] +.SH DESCRIPTION +.I Ntpq +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. +.I Ntpq +can also obtain and print a list of peers in a common format +by sending multiple queries to the server. +.PP +If one or more request options is included on the command line when +.I ntpq +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 +.I localhost +by default. If no request options are given, +.I ntpq +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 +.I localhost +when no other host is specified. +.I Ntpq +will prompt for commands if the standard input is a terminal device. +.PP +.I Ntpq +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. +.I Ntpq +makes one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable time out time. +.PP +Command line options are described following. Specifying a command +line option other than +.B -i +or +.B -n +will cause the specified query (queries) to be sent to the indicated +host(s) immediately. Otherwise, +.I ntpq +will attempt to read interactive format commands from the standard input. +.Ip -c 8 +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 +.B -c +options may be given. +.Ip -i 8 +Force +.I ntpq +to operate in interactive mode. Prompts will be written to the +standard output and commands read from the standard input. +.Ip -n 8 +Output all host addresses in dotted\-quad numeric format rather than +converting to the canonical host names. +.Ip -p 8 +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the \*(L"peers\*(R" interactive +command. +.SH INTERNAL COMMANDS +.PP +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 \*(L">\*(R", +followed by a file name, to the command line. +.PP +A number of interactive format commands are executed entirely within the +.I ntpq +program itself and do not result in NTP mode 6 requests being sent +to a server. These are described following. +.PP +.B ? +[ +.I command_keyword +} +.PP +A \*(L"?\*(R" by itself will print a list of all the command keywords +known to this incarnation of +.IR ntpq . +A \*(L"?\*(R" followed by a command keyword will print funcation and +usage information about the command. This command is probably a better +source of information about +.I ntpq +than this manual page. +.PP +.B timeout +.I millseconds +.PP +Specify a time out period for responses to server queries. The default +is about 5000 milliseconds. Note that since +.I ntpq +retries each query once after a time out the total waiting time for a +time out will be twice the time out value set. +.PP +.B delay +.I milliseconds +.PP +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 +time stamps in authenticated requests, so this command may be obsolete. +.PP +.B host +.I hostname +.PP +Set the host to which future queries will be sent. +.I Hostname +may be either a host name or a numeric +address. +.PP +.B poll +[ +.I # +] [ +.B verbose +] +.PP +Poll the current server in client mode. The first argument is the +number of times to poll (default is 1) while the second argument may +be given to obtain a more detailed output of the results. This command +is currently just wishful thinking. +.PP +.B keyid +.I # +.PP +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. +.PP +.B passwd +.PP +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. +.PP +.B "hostnames yes|no" +.PP +If \*(L"yes\*(R" is specified, host names are printed in information +displays. If \*(L"no\*(R" is given, numeric addresses are printed +instead. The default is \*(L"yes\*(R" unless modified using the command +line +.B -n +switch. +.PP +.B raw +.PP +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. +.PP +.B cooked +.PP +Causes output from query commands to be \*(L"cooked\*(R". Variables +which are recognized by the server will have their values reformatted +for human consumption. Variables which +.I ntpq +thinks should have a decodeable value but didn't are marked with a +trailing \*(L"?\*(R". +.PP +.B ntpversion +.B 1|2|3 +.PP +Sets the NTP version number which +.I ntpq +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. +.PP +.B authenticate +.B yes|no +.PP +Normally +.I ntpq +does not authenticate requests unless they are write requests. The command +.B authenticate yes +causes +.I ntpq +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. +.PP +.B addvars +.IR <variable_name>[=<value>] [,...] +.B rmvars +.IR <variable_name> [,...] +.B clearvars +.PP +The data carried by NTP mode 6 messages consists of a list of items +of the form +.IP "" 8 +<variable_name>=<value> +.PP +where the \*(L"=<value>\*(R" is ignored, and can be omitted, in requests +to the server to read variables. +.I Ntpq +maintains an internal list in which data to be included in control messages +can be assembled, and sent using +the +.B readlist +and +.B writelist +commands described below. The +.B 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 +.B rmvars +command can be used to remove individual variables from the list, while +the +.B clearlist +command removes all variables from the list. +.PP +.B debug +.I more|less|off +.PP +Turns internal query program debugging on and off. +.PP +.B quit +.PP +Exit +.IR ntpq . +.SH CONTROL MESSAGE COMMANDS +.PP +Each peer known to an NTP server has a 16 bit integer +.I association +.I 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. +.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 +.B peers +command, which will send a preprogrammed series of messages to obtain +the data it needs, and the +.B mreadlist +and +.B mreadvar +commands, which will iterate over a range of associations. +.PP +.B associations +.PP +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. Note +that the data returned by the \*(L"associations\*(R" command is cached +internally in +.IR ntpq . +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 +.I &index +may be used as an alternative. +.PP +.B lassocations +.PP +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 +\*(L"associations\*(R" +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 +\*(L"associations\*(R" +command is used, but are included in the output of +\*(L"lassociations\*(R". +.PP +.B passociations +.PP +Prints association data concerning in\-spec peers from the internally cached +list of associations. This command performs +identically to the \*(L"associations\*(R" except that it displays the +internally stored data rather than making a new query. +.PP +.B lpassociations +.PP +Print data for all associations, including out\-of\-spec client +associations, from the internally cached list of associations. This command +differs from \*(L"passociations\*(R" only when dealing with fuzzballs. +.PP +.B pstatus +.I assocID +.PP +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. +.PP +.B readvar +[ +.I assocID +] [ +.IR <variable_name>[=<value>] [,...] +] +.PP +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. +.PP +.B rv +[ +.I assocID +] [ +.IR <variable_name>[=<value>] [,...] +] +.PP +An easy\-to\-type short form for the +.B readvar +command. +.PP +.B writevar +.I assocID +.IR <variable_name>=<value> [,...] +.PP +Like the +.B readvar +request, except the specified variables are written instead of read. +.PP +.B readlist +[ +.I assocID +] +.PP +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. +.PP +.B rl +[ +.I assocID +] +.PP +An easy\-to\-type short form of the +.B readlist +command. +.PP +.B writelist +[ +.I assocID +] +.PP +Like the +.B readlist +request, except the internal list variables are written instead of +read. +.PP +.B mreadvar +.I assocID +.I assocID +[ +.IR <variable_name>[=<value>] [,...] +] +.PP +Like the +.B 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 +.B associations +command. +.PP +.B mrv +.I assocID +.I assocID +[ +.IR <variable_name>[=<value>] [,...] +] +.PP +An easy\-to\-type short form of the +.B mreadvar +command. +.PP +.B mreadlist +.I assocID +.I assocID +.PP +Like the +.B 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 +.B associations +command. +.PP +.B mrl +.I assocID +.I assocID +.PP +An easy\-to\-type short form of the +.B mreadlist +command. +.PP +.B clockvar +[ +.I assocID +] +[ +.IR <variable_name>[=<value>] [,...] +] +.PP +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 \*(L"system clock\*(R" 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. +.PP +.B cv +[ +.I assocID +] +[ +.IR <variable_name>[=<value>] [,...] +] +.PP +An easy\-to\-type short form of the +.B clockvar +command. +.PP +.B peers +.PP +Obtains a list of in\-spec 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 the refID is unknown), +the stratum of the remote peer, the polling interval, +in seconds, the reachability +register, in octal, and the current estimated delay, offset and dispersion +of the peer, all in seconds. +.PP +The character in the left margin indicates the fate of this peer in the +clock selection process. The codes mean: <sp> discarded due to high stratum +and/or failed sanity checks; \*(L"x\*(R" designated falsticker by the +intersection algorithm; \*(L".\*(R" culled from the end of the candidate +list; \*(L"-\*(R" discarded by the clustering algorithmi; \*(L"+\*(R" +included in the final selection set; \*(L"#\*(R" selected for synchronizatio;n +but distance exceeds maximum; \*(L"*\*(R" selected for synchronization; and +\*(L"o\*(R" selected for synchronization, pps signal in use. +.PP +Note that since the +.B peers +command depends on the ability to parse the values in the +responses it gets it may fail to work from time to time with servers +which poorly control the data formats. +.PP +The contents of the host field may be one of four forms. It may be a host name, +an IP address, a reference clock implementation name with its parameter or +\*(L"REFCLK(<implementation number>, <parameter>)\*(R". On \*(L"hostnames no\*(R" +only IP\-addresses will be displayed. +.PP +.B lpeers +.PP +Like +.BR 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. +.PP +.B opeers +.PP +An old form of the \*(L"peers\*(R" command with the reference ID +replaced by the local interface address. +.SH HISTORY +.PP +Written by Dennis Ferguson at the University of Toronto. +.SH BUGS +.PP +The +.B peers +command is non\-atomic and may occasionally result in spurious error +messages about invalid associations occuring and terminating the +command. +.PP +The timeout time is a fixed constant, which means you wait a long time +for time outs since it assumes sort of a worst case. The program +should improve the time out estimate as it sends queries to a particular +host, but doesn't. |
