diff options
Diffstat (limited to 'usr.sbin/xntpd/doc/ntpq.8')
| -rw-r--r-- | usr.sbin/xntpd/doc/ntpq.8 | 480 |
1 files changed, 0 insertions, 480 deletions
diff --git a/usr.sbin/xntpd/doc/ntpq.8 b/usr.sbin/xntpd/doc/ntpq.8 deleted file mode 100644 index 7d62428..0000000 --- a/usr.sbin/xntpd/doc/ntpq.8 +++ /dev/null @@ -1,480 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd December 21, 1993 -.Dt NTPQ 8 -.Os -.Sh NAME -.Nm ntpq -.Nd standard Network Time Protocol query program -.Sh SYNOPSIS -.Nm -.Op Fl inp -.Op Fl c Ar command -.Op Ar host ... -.Sh DESCRIPTION -.Nm 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. -.Nm 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 -.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 -.Ar 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 -.Ar localhost -when no other host is specified. -.Nm Ntpq -will prompt for commands if the standard input is a terminal device. -.Pp -.Nm Ntpq -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. -.Nm 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 -.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. -The following options are available: -.Bl -tag -width indent -.It Fl c Ar command -The following argument is interpreted as an interactive format -.Ar 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 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 -.Em peers -interactive command. -.El -.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 -.Qq > , -followed by a file name, to the command line. -.Pp -A number of interactive format commands are executed entirely within the -.Nm -program itself and do not result in NTP mode 6 requests being sent to a -server. These are described following. -.Pp -.Bl -tag -width indent -.It ? Op Ar command_keyword -A -.Qq ? -by itself will print a list of all the command keywords -known to this incarnation of -.Nm Ns . -A -.Qq ? -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 timeout Ar milliseconds -Specify a time out period for responses to server queries. The default -is about 5000 milliseconds. Note that since -.Nm -retries each query once after a time out the total waiting time for a -time out will be twice the time out value set. -.It 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 time -stamps in authenticated requests, so this command may be obsolete. -.It host Ar hostname -Set the host to which future queries will be sent. -.Ar Hostname -may be either a host name or a numeric -address. -.It Xo poll -.Op Ar # -.Op Ar verbose -.Xc -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. -.It keyid Ar # -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. -.It passwd -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. -.It hostnames Ar yes | Ar no -If -.Ar yes -is specified, host names are printed in information -displays. If -.Ar no -is given, numeric addresses are printed -instead. The default is -.Ar yes -unless modified using the command line -.Fl n -switch. -.It raw -Cause all output from query commands is printed as received from the -remote server. The only formating/intepretation done on the data is to -transform non-ASCII data into a printable (but barely understandable) -form. -.It cooked -Cause output from query commands to be -.Qq cooked Ns . -Variables -which are recognized by the server will have their values reformatted -for human consumption. Variables which -.Nm -thinks should have a decodeable value but didn't are marked with a -trailing -.Qq ? Ns . -.It ntpversion Ar 1 | Ar 2 | Ar 3 -Set the NTP version number which -.Nm -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. -.It authenticate Ar yes | Ar no -Normally -.Nm -does not authenticate requests unless they are write requests. The -command -.Em authenticate yes -causes -.Nm -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. -.It Xo addvars -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,... -.Xc -.It Xo rmvars -.Aq variable_name Ns -.Op ,... -.Xc -.It clearvars -The data carried by NTP mode 6 messages consists of a list of items of -the form -.Xo Aq variable_name Ns -.Pf = Aq value -.Xc -where the -.Qq = Ns Aq value -is ignored, and can be omitted, in requests -to the server to read variables. -.Nm Ntpq -maintains an internal list in which data to be included in control -messages can be assembled, and sent using the -.Em readlist -and -.Em writelist -commands described below. The -.Em 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 -.Em rmvars -command can be used to remove individual variables from the list, while -the -.Em clearlist -command removes all variables from the list. -.It debug Ar more | Ar less | Ar off -Turn internal query program debugging on and off. -.It quit -Exit -.Nm Ns . -.El -.Sh CONTROL MESSAGE COMMANDS -Each peer known to an NTP server has a 16 bit integer -.Em 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. -.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 -.Em peers -command, which will send a preprogrammed series of messages to obtain -the data it needs, and the -.Em mreadlist -and -.Em mreadvar -commands, which will iterate over a range of associations. -.Bl -tag -width indent -.It associations -Obtain and print 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 -.Nm Ns . -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 -.Em &index -may be used as an alternative. -.It lassocations -Obtain and print a list of association identifiers and peer statuses -for all associations for which the server is maintaining state. This -command differs from the -.Em 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 -.Em associations -command is used, but are included in the -output of -.Em lassociations Ns . -.It passociations -Print association data concerning in\-spec peers from the internally -cached list of associations. This command performs identically to the -.Em associations -except that it displays the internally stored -data rather than making a new query. -.It lpassociations -Print data for all associations, including out\-of\-spec client -associations, from the internally cached list of associations. This -command differs from -.Em passociations -only when dealing with fuzzballs. -.It pstatus Ar assocID -Send 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 pidgin English. -.It Xo readvar -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -Request 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. -.It Xo rv -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -An easy\-to\-type short form for the -.Em readvar -command. -.It Xo writevar -.Ar assocID -.Aq variable_name Ns -.Pf = Ns Aq value Ns -.Op ,... -.Xc -Like the -.Em readvar -request, except the specified variables are written instead of read. -.It readlist Op Ar assocID -Request 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 rl Op Ar assocID -An easy\-to\-type short form of the -.Em readlist -command. -.It writelist Op Ar assocID -Like the -.Em readlist -request, except the internal list variables are written instead of read. -.It Xo mreadvar -.Ar assocID assocID [ -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -Like the -.Em 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 -.Em associations -command. -.It Xo mrv -.Ar assocID assocID [ -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -An easy\-to\-type short form of the -.Em mreadvar -command. -.It mreadlist Ar assocID assocID -Like the -.Em 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 -.Em associations -command. -.It mrl Ar assocID assocID -An easy\-to\-type short form of the -.Em mreadlist -command. -.It Xo clockvar -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -Request 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 -.Qq 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 Xo cv -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] -.Xc -An easy\-to\-type short form of the -.Em clockvar -command. -.It peers -Obtain 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 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 -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; -.Qq x -designated falsticker -by the intersection algorithm; -.Qq \&. -culled from the end of the -candidate list; -.Qq - -discarded by the clustering algorithm; -.Qq + -included in the final selection set; -.Qq # -selected -for synchronization but distance exceeds maximum; -.Qq * -selected -for synchronization; and -.Qq o -selected for synchronization, pps -signal in use. -.Pp -Note that since the -.Em 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 -.Qq REFCLK(<implementation number>, <parameter>) . -On -.Qq hostnames no -only IP\-addresses will be displayed. -.It lpeers -Like -.Em 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 opeers -An old form of the -.Em peers -command with the reference ID -replaced by the local interface address. -.El -.Sh HISTORY -Written by -.An Dennis Ferguson -at the University of Toronto. -.Sh BUGS -The -.Em peers -command is non\-atomic and may occasionally result in spurious error -messages about invalid associations occurring 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. |
