diff options
Diffstat (limited to 'usr.sbin/ntp/doc/ntpq.8')
| -rw-r--r-- | usr.sbin/ntp/doc/ntpq.8 | 851 |
1 files changed, 0 insertions, 851 deletions
diff --git a/usr.sbin/ntp/doc/ntpq.8 b/usr.sbin/ntp/doc/ntpq.8 deleted file mode 100644 index 0a47c76..0000000 --- a/usr.sbin/ntp/doc/ntpq.8 +++ /dev/null @@ -1,851 +0,0 @@ -.\" -.\" $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. |
