diff options
Diffstat (limited to 'usr.sbin/ntp/doc/ntpq.8')
| -rw-r--r-- | usr.sbin/ntp/doc/ntpq.8 | 1000 |
1 files changed, 571 insertions, 429 deletions
diff --git a/usr.sbin/ntp/doc/ntpq.8 b/usr.sbin/ntp/doc/ntpq.8 index d2f8998..717a8e2 100644 --- a/usr.sbin/ntp/doc/ntpq.8 +++ b/usr.sbin/ntp/doc/ntpq.8 @@ -13,66 +13,65 @@ .Op Fl c Ar command .Op Ar host ... .Sh DESCRIPTION +The .Nm -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. +utility program 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 -can also obtain and print a list of peers in a common format by sending -multiple queries to the server. +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 +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 -.Dq localhost -by default. -If no request options are given, +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 -.Dq localhost +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. .Nm -will prompt for commands if the standard input is a terminal device. +will prompt for +commands if the standard input is a terminal device. .Pp .Nm -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. +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 -makes one attempt to retransmit requests, and will time requests out if -the remote host is not heard from within a suitable timeout time. +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 -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 command -and is added to the list of commands to be executed on the specified -host(s). +.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. @@ -80,72 +79,78 @@ options may be given. Force .Nm to operate in interactive mode. -Prompts will be written to the standard -output and commands read from the standard input. +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. +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. +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 -.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 -.Qq > , +.Pp +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 +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. +program 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 \&? Op Ar command_keyword .It Ic help Op Ar command_keyword A -.Ic ?\& -by itself will print a list of all the command keywords -known to this incarnation of +.Ql \&? +by itself will print a list of all the command +keywords known to this incarnation of .Nm . A -.Ic ?\& -followed by a command keyword will print function and -usage information about the command. +.Ql \&? +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. -.\" -.\" XXX Both variable_name and value below should be arguments, -.\" not angle-quoted text. -.\" +than this manual +page. .It Xo Ic addvars -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,... -.Xc -.It Xo Ic rmvars -.Aq variable_name Ns -.Op ,... +.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 -.Sm off -.Ao variable_name Ac = Aq value -.Sm on +The data carried by NTP mode 6 messages consists of a list of +items of the form +.Ql variable_name=value , where the -.Qq = Ns Aq value -is ignored, and can be omitted, in requests -to the server to read variables. +.Ql =value +is ignored, and can be omitted, +in requests to the server to read variables. .Nm maintains an internal list in which data to be included in control messages can be assembled, and sent using the @@ -155,244 +160,250 @@ and 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. +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 clearvars -command removes all variables from the list. -.It Ic authenticate Ar yes | Ar no +command can be used to remove individual variables from the list, +while the +.Ic clearlist +command removes all variables from the +list. +.It Ic authenticate Cm yes | Cm no Normally .Nm -does not authenticate requests unless they are write requests. +does not authenticate requests unless +they are write requests. The command -.Dq Li authenticate yes +.Ql authenticate yes causes .Nm -to send authentication with all requests it makes. -Authenticated requests cause 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. +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 +.Ic peer +display. .It Ic cooked -Causes output from query commands to be -.Qq cooked Ns . -Variables -which are recognized by the server will have their values reformatted -for human consumption. +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 decodeable value but didn't are marked with a -trailing -.Qq ? Ns . -.It Ic debug Xo -.Ar more | Ar less | Ar off +thinks should have a decodable value but didn't are +marked with a trailing +.Ql \&? . +.It Xo Ic debug +.Cm more | +.Cm less | +.Cm off .Xc -Turn internal query program debugging on and off. +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, +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. -The -.Ar hostname -supplied -may be either a host name or a numeric -address. -.It Ic hostnames Ar yes | Ar no +Hostname may +be either a host name or a numeric address. +.It Ic hostnames Cm yes | Cm no If -.Ar yes -is specified, host names are printed in information -displays. +.Cm yes +is specified, host names are printed in +information displays. If -.Ar no -is given, numeric addresses are printed -instead. +.Cm no +is specified, numeric +addresses are printed instead. The default is -.Ar yes -unless modified using the command line +.Cm yes , +unless +modified using the command line .Fl n switch. .It Ic keyid Ar keyid -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 Ic ntpversion Xo -.Ar 1 | Ar 2 | -.Ar 3 | Ar 4 +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 Xo Ic ntpversion +.Cm 1 | +.Cm 2 | +.Cm 3 | +.Cm 4 .Xc -Set the NTP version number which +Sets 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. +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 Ic quit Exit .Nm . .It Ic 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. +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 Ic raw -Cause all output from query commands -to be printed as received from the remote server. -The only formatting and intepretation done on the data is to -transform non-ASCII data into a printable (but barely understandable) -form. +Causes all output from query commands is printed as received +from the remote server. +The only formating/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. +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. +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 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. +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. .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 -.Ic peers -command, -which will send a preprogrammed series of messages to obtain -the data it needs, and the -.Ic mreadlist -and -.Ic mreadvar -commands, which will iterate over a range of associations. +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. +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 +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 -.Dq Li &index -may be used as an alternative. -.\" -.\" XXX Both variable_name and value below should be arguments, -.\" not angle-quoted text. -.\" -.It Xo Ic clockvar -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] +command is cached internally +in +.Xr ntpq 8 . +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 Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] +.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 -.Qq system clock -and will -generally get a positive response from all servers with a clock. +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. +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. +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 +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 Ns . +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 +This +command differs from .Ic passociations -only when dealing with fuzzballs. +only when dealing with +fuzzballs. .It Ic lpeers -Like -.Ic 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 assocID -.It Ic mrl Ar assocID assocID +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 +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 assocID Oo -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,... Oc +.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 assocID Oo -.Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,... Oc +.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 +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 @@ -400,203 +411,334 @@ An old form of the .Ic peers command with the reference ID replaced by the local interface address. -.It Ic passociations -Print association data concerning in-spec peers from the internally -cached list of associations. -This command performs identically to the +.It Ic passocations +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. +except that it displays +the internally stored data rather than making a new query. .It Ic peers -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 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. -.Pp -The character in the left margin indicates the fate of this peer in the -clock selection process. -Following is a list of these characters, -the pidgeon used in the +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 in the left margin indicates the fate of this +peer 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. +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. +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 . +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 - +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 candidate -The peer is a survivor and a candidate for the combining algorithm. -.It # +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, +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. -.It * -.Pq sys.peer -The peer has been declared the system peer -and lends its variables to the system variables. +.It \&* +.Pq 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. +.Pq (pps.peer) +The peer has been declared the system peer and lends its +variables to thesystem 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 .El .Pp -The flash 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 TEST1 through TEST9. -The bits for each test read in increasing sequency -from the least significant bit -and are defined as follows. +The +.Va flash +variable is a valuable debugging aid. +It +displays the results of the original sanity checks defined in the +NTP specification RFC-1305 and additional ones added in NTP Version +4. +There are eleven tests called +.Sy TEST1 +through +.Sy TEST11 . +The tests are performed in a certain order +designed to gain maximum diagnostic information while protecting +against accidental or malicious errors. +The +.Va flash +variable +is first initialized to zero. +If after each set of tests one or +more bits are set, the packet is discarded. +.Pp +Tests +.Sy TEST4 +and +.Sy TEST5 +check the access +permissions and cryptographic message digest. +If any bits are set +after that, the packet is discarded. +Tests +.Sy TEST10 +and +.Sy TEST11 +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 following TEST1 through TEST4 enumerate procedure errors. -The packet timestamps may or may not be believed, -but the remaining header data are ignored. +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. +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. +Test +.Sy 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 +The +.Va flash +bits for each test read in increasing order +from the least significant bit are defined as follows. .Bl -tag -width indent -.It TEST1 +.It Sy TEST1 Duplicate packet. -A copy from somewhere. -.It TEST2 +The packet is at best a casual retransmission +and at worst a malicious replay. +.It Sy TEST2 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. -.It TEST3 +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 Sy TEST3 Unsynchronized. -One or more timestamp fields are missing. -This normally happens when the first packet from a peer is received. -.It TEST4 -Either peer delay or peer dispersion is greater than one second. -You must be joking. -.El -.Pp -The following TEST5 through TEST10 -enumerate errors in the packet header. -The packet is discarded without inspecting its contents. -.Bl -tag -width indent -.It TEST5 -Cryptographic authentication fails. +One or more timestamp fields are invalid. +This +normally happens when the first packet from a peer is +received. +.It Sy TEST4 +Access is denied. See the -.Qq Authentication Support -section of the -.Xr ntp.conf 5 +.Qq "Access Control" page. -.It TEST6 -Peer is unsynchronized. +.It Sy TEST5 +Cryptographic authentication fails. +See the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +.It Sy TEST6 +The server is unsynchronized. Wind up its clock first. -.It TEST7 -Peer stratum is greater than 15. -The peer is probably unsynchronized. -.It TEST8 -Either root delay or root dispersion is greater than one second. -Too far from home. -.It TEST9 -Peer cryptographic authentication fails. -Either the key identifier or key is wrong -or somebody trashed our packet. -.It TEST10 -Access is denied. +.It Sy TEST7 +The server stratum is at the maximum than 15. +It is probably +unsynchronized and its clock needs to be wound up. +.It Sy TEST8 +Either the root delay or dispersion is greater than one second, +which is highly unlikely unless the peer is synchronized to +Mars. +.It Sy TEST9 +Either the peer delay or dispersion is greater than one second, +which is higly unlikely unless the peer is on Mars. +.It Sy TEST10 +The autokey protocol has detected an authentication failure. See the -.Qq Access Control Support -section of the -.Xr ntp.conf 5 -page. +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +.It Sy TEST11 +The autokey protocol has not verified the server or peer is +authentic and has valid public key credentials. +See the +.Sx Authentication Options +section of +.Xr ntp.conf 5 . +.El +.Pp +Additional system variables used by the NTP Version 4 Autokey +support include the following: +.Bl -tag -width indent +.It Ic certificate Ar filestamp +Shows the NTP seconds when the certificate file was +created. +.It Ic hostname Ar host +Shows the name of the host as returned by the Unix +.Xr gethostname 3 +library function. +.It Ic flags Ar hex +Shows the current flag bits, where the +.Ar hex +bits +are interpreted as follows: +.Bl -tag -width indent +.It 0x01 +autokey enabled +.It 0x02 +RSA public/private key files present +.It 0x04 +PKI certificate file present +.It 0x08 +Diffie-Hellman parameters file present +.It 0x10 +NIST leapseconds table file present .El +.It Ic leapseconds Ar filestamp +Shows the NTP seconds when the NIST leapseconds table file was +created. +.It Ic params Ar filestamp +Shows the NTP seconds when the Diffie-Hellman agreement +parameter file was created. +.It Ic publickey Ar filestamp +Shows the NTP seconds when the RSA public/private key files +were created. +.It Ic refresh Ar filestamp +Shows the NTP seconds when the public cryptographic values were +refreshed and signed. +.It Ic tai Ar offset +Shows the TAI-UTC offset in seconds obtained from the NIST +leapseconds table. +.El +.Pp +Additional peer variables used by the NTP Version 4 Autokey +support include the following: +.Bl -tag -width indent +.It Ic certificate Ar filestamp +Shows the NTP seconds when the certificate file was +created. +.It Ic flags Ar hex +Shows the current flag bits, where the +.Ar hex +bits are +interpreted as in the system variable of the same name. +The bits +are set in the first autokey message received from the server and +then reset as the associated data are obtained from the server and +stored. +.It Ic hcookie Ar hex +Shows the host cookie used in the key agreement algorithm. +.It Ic initkey Ar key +Shows the initial key used by the key list generator in the +autokey protocol. +.It Ic initsequence Ar index +Shows the initial index used by the key list generator in the +autokey protocol. +.It Ic pcookie Ar hex +Specifies the peer cookie used in the key agreement +algorithm. +.It Ic timestamp Ar time +Shows the NTP seconds when the last autokey key list was +generated and signed. .It Ic 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 pidgeon English. -.It Ic readlist Op Ar assocID -.It Ic rl Op 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. +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. +.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. -.\" -.\" XXX Both variable_name and value below should be arguments, -.\" not angle-quoted text. -.\" -.It Xo Ic readvar -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] +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 -.Op Ar assocID Ns -.Pf [ Aq variable_name Ns -.Op = Ns Aq value Ns -.Op ,...] +.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. -.It Xo Ic writevar -.Ar assocID -.Aq variable_name Ns -.Pf = Ns Aq value Ns -.Op ,... +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. +.It Xo Ic writevar Ar assocID +.Ar variable_name Ns Op = Ns Ar value +.Ar ... .Xc -Like the -.Ic readvar -request, except the specified variables are written instead of read. +Like the readvar request, except the specified variables are +written instead of read. .It Ic writelist Op Ar assocID -Like the -.Ic readlist -request, except the internal list variables are written instead of read. +Like the readlist request, except the internal list variables +are written instead of read. .El .Sh SEE ALSO .Xr ntp.conf 5 , .Xr ntpd 8 , .Xr ntpdc 8 -.Sh HISTORY -Written by -.An Dennis Ferguson -at the University of Toronto. .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 doesn't. +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. |
