diff options
Diffstat (limited to 'usr.sbin/xntpd/doc/xntpdc.8')
| -rw-r--r-- | usr.sbin/xntpd/doc/xntpdc.8 | 659 |
1 files changed, 659 insertions, 0 deletions
diff --git a/usr.sbin/xntpd/doc/xntpdc.8 b/usr.sbin/xntpd/doc/xntpdc.8 new file mode 100644 index 0000000..20209b5 --- /dev/null +++ b/usr.sbin/xntpd/doc/xntpdc.8 @@ -0,0 +1,659 @@ +''' $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 XNTPDC 8 LOCAL +.SH NAME +xntpdc - query/control program for the Network Time Protocol daemon +.SH SYNOPSIS +.B xntpdc +[ +.B -ilnps +] [ +.B -c +.I command +] [ +.I host +] [ +.I ... +] +.SH DESCRIPTION +.I Xntpdc +is used to query the +.IR xntpd (8) +daemon about its current state and to request changes in that state. The +program may be run either in interactive mode or controlled using +command line arguments. Extensive state and statistics information is +available through the +.I xntpdc +interface. In addition, nearly all the configuration options which can +be specified at start up using +.IR xntpd 's +configuration file may also be specified at run time using +.IR xntpdc . +.PP +If one or more request options is included on the command line when +.I xntpdc +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 xntpdc +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 Xntpdc +will prompt for commands if the standard input is a terminal device. +.PP +.I Xntpdc +uses NTP mode 7 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 Xntpdc +makes no 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 xntpdc +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 xntpdc +to operate in interactive mode. Prompts will be written to the +standard output and commands read from the standard input. +.Ip -l 8 +Obtain a list of peers which are known to the server(s). This switch +is equivalent to \*(L"-c listpeers\*(R". +.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 \*(L"-c peers\*(R". +.Ip -s 8 +Print a list of the peers known to the server as well as a summary +of their state, but in a slightly different format than the +.B -p +switch. This is equivalent to \*(L"-c dmpeers\*(R". +.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 xntpdc +program itself and do not result in NTP mode 7 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 xntpdc . +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 xntpdc +than this manual page. +.PP +.B help +[ +.I command_keyword +] +.PP +A synonym for the +.B ? +command. +.PP +.B timeout +.I millseconds +.PP +Specify a time out period for responses to server queries. The default +is about 8000 milliseconds. +.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. +.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 the +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 quit +.PP +Exit +.IR xntpdc . +.SH QUERY COMMANDS +.PP +Query commands result in NTP mode 7 packets containing requests for +information being sent to the server. These are \*(L"read\-only\*(R" +commands in that they make no modification of the server configuration +state. +.PP +.B listpeers +.PP +Obtains and prints a brief list of the peers for which the +server is maintaining state. These should include all configured +peer associations as well as those peers whose stratum is such that +they are considered by the server to be possible future synchonization +candidates. +.PP +.B peers +.PP +Obtains a list of peers for which the server is maintaining state, along +with a summary of that state. Summary information includes the address +of the remote peer, the local interface address (0.0.0.0 if a local address +has yet to be determined), the stratum of the remote peer (a stratum of +16 indicates the remote peer is unsynchronized), the polling interval, +in seconds, the reachability +register, in octal, and the current estimated delay, offset and dispersion +of the peer, all in seconds. In addition, the character in the left +margin indicates the mode this peer entry is operating in. A +\*(L"+\*(R" denotes symmetric active, a \*(L"-\*(R" indicates symmetric +passive, a \*(L"=\*(R" means the remote server is being polled in +client mode, a \*(L"^\*(R" indicates that the server is broadcasting +to this address, a \*(L"~\*(R" denotes that the remote peer is sending +broadcasts and a \*(L"*\*(R" marks the peer the server is currently +synchonizing to. +.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 dmpeers +.PP +A slightly different peer summary list. Identical to the output of the +.B peers +command except for the character in the leftmost column. Characters +only appear beside peers which were included in the final stage of +the clock selection algorithm. A \*(L".\*(R" indicates that this +peer was cast off in the falseticker detection, while a \*(L"+\*(R" +indicates that the peer made it through. A \*(L"*\*(R" denotes the +peer the server is currently synchronizing with. +.PP +.B showpeer +.I peer_address +[ +.I addr2 +] [ +.I addr3 +] [ +.I addr4 +] +.PP +Shows a detailed display of the current peer variables for one or more +peers. Most of these values are described in the NTP Version 2 +specification. +.PP +.B pstats +.I peer_address +[ +.I addr2 +] [ +.I addr3 +] [ +.I addr4 +] +.PP +Show per\-peer statistic counters associated with the specified peer(s). +.PP +.B loopinfo +[ +.B oneline|multiline +] +.PP +Print the values of selected loop filter variables. The loop filter is +the part of NTP which deals with adjusting the local system clock. The +\*(L"offset\*(R" is the last offset given to the loop filter by the +packet processing code. The \*(L"frequency\*(R" is actually the +frequency error, or drift, of your system's clock in the units NTP +uses for internal computations. Dividing this number by 4096 should +give you the actual drift rate. The \*(L"compliance\*(R" is actually +a long term average offset and is used by NTP to control the gain of +the loop filter. The \*(L"timer\*(R" value is the number of seconds +which have elapsed since a new sample offset was given to the loop +filter. The \*(L"oneline\*(R" and \*(L"multiline\*(R" options specify +the format in which this information is to be printed. \*(L"multiline\*(R" +is the default. +.PP +.B sysinfo +.PP +Print a variety of system state variables, i.e. state related to the +local server. Many of these values are described in the NTP Version 2 +specification, RFC 1119. +.PP +.B sysstats +.PP +Print a number of stat counters maintained in the protocol module. +.PP +.B memstats +.PP +Print a number of counters related to the peer memory allocation +code. +.PP +.B iostats +.PP +Print counters maintained in the input\-output module. +.PP +.B timerstats +.PP +Print counters maintained in the timer/event queue support code. +.PP +.B reslist +.PP +Obtain and print the server's restriction list. This list is (usually) +printed in sorted order and may help to understand how the restrictions +are applied. +.PP +.B monlist +.PP +Obtain and print traffic counts collected and maintained by the +monitor facility. +.PP +.B clockinfo +.I clock_peer_address +[ +.I addr2 +] [ +.I addr3 +] [ +.I addr4 +] +.PP +Obtain and print information concerning a peer clock. The values +obtained provide information on the setting of fudge factors and +other clock performance information. +.PP +.B clkbug +.I clock_peer_address +[ +.I addr2 +] [ +.I addr3 +] [ +.I addr4 +] +.PP +Obtain debugging information for a clock peer. This information is +provided only by some clock drivers and is mostly undecodable without +a copy of the driver source in hand. +.SH RUNTIME CONFIGURATION REQUESTS +.PP +All requests which cause state changes in the server are authenticated +by the server using a configured NTP key (the facility can also be +disabled by +the server by not configuring a key). The key number and the corresponding +key must also be made known to +.IR xtnpdc . +This can be done using the +.B keyid +and +.B passwd +commands, the latter of which will prompt at the +terminal for a password to use +as the encryption key. You will also be prompted automatically for +both the key number and password the +first time a command which would result in an authenticated request +to the server is given. Authentication not only provides verification +that the requester has permission to make such changes, but also gives +an extra degree of protection again transmission errors. +.PP +Authenticated requests always include a timestamp in the packet data, which +is included in the computation of the authentication code. This timestamp +is compared by the server to its receive time stamp. If they differ +by more than a small amount the request is rejected. This is done for +two reasons. First, it makes simple replay attacks on the server, by someone +who might be able to overhear traffic on your LAN, much more difficult. +Second, it makes it more difficult to request configuration changes +to your server from topologically remote hosts. While the reconfiguration +facility will work well with a server on the local host, and may work +adequately between time\-synchronized hosts on the same LAN, it will +work very poorly for more distant hosts. As such, if reasonable passwords +are chosen, care is taken in the distribution and protection of keys and +appropriate source address restrictions are applied, the +run time reconfiguration facility should provide an adequate level of +security. +.PP +The following commands all make authenticated requests. +.PP +.B addpeer +.I peer_address +[ +.I keyid +] [ +.I version# +] [ +.B minpoll|prefer +] +.PP +Add a configured, symmetric active peer association with a peer at the +given address. If the optional \*(L"keyid\*(R" is a nonzero integer +all outgoing packets to the remote server will +have an authentication field attached encrypted with this key. If the +value is 0 (or not given) no authentication will be done. The +\*(L"version#\*(R" can be 1 or 2, and defaults to 2. If \*(L"minpoll\*(R" +is specified the polling interval for the association will remain +clamped at the minimum. The latter option is only useful for testing. +Note that an existing association with the same peer may be deleted +when this command is executed, or may simply be converted to conform to +the new configuration, as appropriate. The prefer keyword indicates +a preferred peer (and thus will be used primarily for clock synchronisation +if possible). The preferred peer also determines the validity of the PPS +signal - if the preferred peer is suitable for synchronisation so is the +PPS signal. +.PP +.B addserver +.I peer_address +[ +.I keyid +] [ +.I version# +] [ +.B minpoll|prefer +] +.PP +Identical to the +.B addpeer +command except that polling is done in client mode rather than +symmetric active mode. +.PP +.B broadcast +.I peer_address +[ +.I keyid +] [ +.I version# +] [ +.B minpoll +] +.PP +Identical to the +.B addpeer +command except that packets are instead sent in broadcast mode. The +\*(L"peer_address\*(R" parameter will generally be a broadcast address +on one of your local networks. +.PP +.B unconfig +.I peer_address +[ +.I addr2 +] [ +.I addr3 +] [ +.I addr4 +] +.PP +This command causes the configured bit to be removed from the specified +peer(s). In many cases this will cause the peer association to be +deleted. When appropriate, however, the association may persist in +an unconfigured mode if the remote peer is willing to continue on in +this fashion. +.PP +.B set bclient|auth +[ +.I ... +] +.PP +Allows the setting of the broadcast client and/or authenticate system +flags. Setting the former causes the server to listen for broadcast +NTP to to synchronize to broadcasts when appropriate. Setting the +latter flag causes the server to only synchronize with peers which +include an authentication field encrypted with one of the local server's +trusted keys. +.PP +.B clear bclient|auth +[ +.I ... +] +.PP +Allows the broadcast client and/or authenticate system flags to be +cleared. Clearing the former causes incoming broadcast NTP packets +to be ignored. Clearing the latter allows peers which have not included +an authentication field, or which have included one but have encrypted +it with an untrusted key, to be considered synchronization candidates. +.PP +.B restrict +.I address +.I mask +.I flag +[ +.I flag +] +.PP +Causes flag(s) to be added to an existing restrict list entry, or adds +a new entry to the list with the specified flag(s). The possible choices +for the flags arguments are given in the following list: +.Ip ignore 10 +Ignore all packets from hosts which match this entry. If this flag +is specified neither queries nor time server polls will be responded +to. +.Ip noquery 10 +Ignore all NTP mode 7 packets (i.e. information queries and configuration +requests) from the source. Time service is not affected. +.Ip nomodify 10 +Ignore all NTP mode 7 packets which attempt to modify the state of the +server (i.e. run time reconfiguration). Queries which return information +are permitted. +.Ip noserve 10 +Ignore NTP packets whose mode is other than 7. In effect, time service is +denied, though queries may still be permitted. +.Ip nopeer 10 +Provide stateless time service to polling hosts, but do not allocate peer +memory resources to these hosts even if they otherwise might be considered +useful as future synchronization partners. +.Ip notrust 10 +Treat these hosts normally in other respects, but never use them as +synchronization sources. +.Ip ntpport 10 +This is actually a match algorithm modifier, rather than a restriction +flag. Its presence causes the restriction entry to be matched only if +the source port in the packet is the standard NTP UDP port (123). Both +\*(L"ntpport\*(R" and non\-\*(L"ntpport\*(R" may be specified. The +\*(L"ntpport\*(R" is considered more specific and is sorted later in the +list. +.PP +.B unrestrict +.I address +.I mask +.I flag +[ +.I flag +] +.PP +Remove the specified flag(s) from the restrict list entry indicated +by the +.I address +and +.I mask +arguments. +.PP +.B delrestrict +.I address +.I mask +[ +.B ntpport +] +.PP +Delete the matching entry from the restrict list. +.PP +.B "monitor yes|no" +.PP +Enable or disable the monitoring facility. Note that a +.B "monitor no" +command followed by a +.B "monitor yes" +command is a good way of resetting the packet counts. +.PP +.B readkeys +.PP +Causes the current set of authentication keys to be purged and a +new set to be obtained by rereading the keys file (which must have +been specified in the +.I xntpd +configuration file). This allows encryption keys to be changed without +restarting the server. +.PP +.B trustkey +.I keyid +[ +.I keyid +] [ +.I keyid +] [ +.I keyid +] +.PP +Adds one or more keys to the trusted key list. When authentication +is enabled, peers whose time is to be trusted must be authenticated using +a trusted key. +.PP +.B untrustkey +.I keyid +[ +.I keyid +] [ +.I keyid +] [ +.I keyid +] +.PP +Removes one or more keys from the trusted key list. +.PP +.B authinfo +.PP +Returns information concerning the authentication module, including +known keys and counts of encryptions and decryptions which have been +done. +.PP +.B setprecision +.I precision_value +.PP +Sets the precision which the server advertises to the specified value. This +should be a negative integer in the range -4 through -20. +.PP +.B setselect +.I algorithm_number +.PP +Sets the selection weight algorithm to that indicated by the specified number. +This should be an integer value between 1 and 5 inclusive. Algorithm 1 +is that specified in RFC 1119, the other 4 algorithms are experimental +and should be used with caution. +.SH SEE ALSO +.PP +.IR xntpd (8) +.SH HISTORY +.PP +Written by Dennis Ferguson at the University of Toronto. +.SH BUGS +.PP +.I Xntpdc +is a crude hack. Much of the information it shows is deadly boring +and could only be loved by its implementer. The program was designed +so that new (and temporary) features were easy to hack in, at great +expense to the program's ease of use. Despite this, the program +is occasionally useful. |
