diff options
Diffstat (limited to 'contrib/ntp/html/ntpdc.htm')
| -rw-r--r-- | contrib/ntp/html/ntpdc.htm | 620 |
1 files changed, 620 insertions, 0 deletions
diff --git a/contrib/ntp/html/ntpdc.htm b/contrib/ntp/html/ntpdc.htm new file mode 100644 index 0000000..52d1fdf --- /dev/null +++ b/contrib/ntp/html/ntpdc.htm @@ -0,0 +1,620 @@ +<HTML> +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META NAME="GENERATOR" CONTENT="Mozilla/4.01 [en] (Win95; I) [Netscape]"> + <TITLE>ntpdc - special NTP query program +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>ntpdc</TT> - special NTP query program</H3> + +<HR> +<H4> +Synopsis</H4> +<TT>ntpdc [ -ilnps ] [ -c <I>command</I> ] [ <I>host</I> ] [ ... ]</TT> +<H4> +Description</H4> +<TT>ntpdc</TT> is used to query the <TT>ntpd</TT> 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 <TT>ntpdc</TT> +interface. In addition, nearly all the configuration options which can +be specified at start up using ntpd's configuration file may also be specified +at run time using <TT>ntpdc</TT>. + +<P>If one or more request options is included on the command line when +<TT>ntpdc</TT> 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, <TT>ntpdc</TT> +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. <TT>ntpdc</TT> +will prompt for commands if the standard input is a terminal device. + +<P><TT>ntpdc</TT> 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. <TT>ntpdc</TT> makes no attempt to retransmit requests, and will +time requests out if the remote host is not heard from within a suitable +timeout time. + +<P>The operation of <TT>ntpdc</TT> are specific to the particular implementation +of the <TT>ntpd</TT> daemon and can be expected to work only with this +and maybe some previous versions of the daemon. Requests from a remote +<TT>ntpdc</TT> program which affect the state of the local server must +be authenticated, which requires both the remote program and local server +share a common key and key identifier. +<H4> +Command Line Options</H4> +Specifying a command line option other than <TT>-i</TT> or <TT>-n</TT> +will cause the specified query (queries) to be sent to the indicated host(s) +immediately. Otherwise, <TT>ntpdc</TT> will attempt to read interactive +format commands from the standard input. +<DL> +<DT> +<TT>-c <I>command</I></TT></DT> + +<DD> +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 -c options may be given.</DD> + +<DT> +<TT>-i</TT></DT> + +<DD> +Force <TT>ntpdc</TT> to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input.</DD> + +<DT> +<TT>-l</TT></DT> + +<DD> +Obtain a list of peers which are known to the server(s). This switch is +equivalent to <TT>-c listpeers</TT>.</DD> + +<DT> +<TT>-n</TT></DT> + +<DD> +Output all host addresses in dotted-quad numeric format rather than converting +to the canonical host names.</DD> + +<DT> +<TT>-p</TT></DT> + +<DD> +Print a list of the peers known to the server as well as a summary of their +state. This is equivalent to <TT>-c peers</TT>.</DD> + +<DT> +<TT>-s</TT></DT> + +<DD> +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 -p switch. This is equivalent +to <TT>-c dmpeers</TT>.</DD> +</DL> + +<H4> +Interactive Commands</H4> +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 <TT><</TT>, followed by a file name, +to the command line. + +<P>A number of interactive format commands are executed entirely within +the <TT>ntpdc</TT> program itself and do not result in NTP mode 7 requests +being sent to a server. These are described following. +<DL> +<DT> +<TT>? [ <I>command_keyword</I> ]</TT></DT> + +<BR><TT>helpl [ <I>command_keyword</I> ]</TT> +<DD> +A <TT>?</TT> by itself will print a list of all the command keywords known +to this incarnation of <TT>ntpq</TT>. A <TT>?</TT> followed by a command +keyword will print funcation and usage information about the command. This +command is probably a better source of information about <TT>ntpq</TT> +than this manual page.</DD> + +<DT> +<TT>delay <I>milliseconds</I></TT></DT> + +<DD> +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.</DD> + +<DT> +<TT>host <I>hostname</I></TT></DT> + +<DD> +Set the host to which future queries will be sent. Hostname may be either +a host name or a numeric address.</DD> + +<DT> +<TT>hostnames [ yes | no ]</TT></DT> + +<DD> +If <TT>yes</TT> is specified, host names are printed in information displays. +If <TT>no</TT> is specified, numeric addresses are printed instead. The +default is <TT>yes</TT>, unless modified using the command line <TT>-n</TT> +switch.</DD> + +<DT> +<TT>keyid <I>keyid</I></TT></DT> + +<DD> +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.</DD> + +<DT> +<TT>quit</TT></DT> + +<DD> +Exit <TT>ntpdc</TT>.</DD> + +<DT> +<TT>passwd</TT></DT> + +<DD> +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.</DD> + +<DT> +<TT>timeout <I>millseconds</I></TT></DT> + +<DD> +Specify a timeout period for responses to server queries. The default is +about 8000 milliseconds. Note that since <TT>ntpdc</TT> retries each query +once after a timeout, the total waiting time for a timeout will be twice +the timeout value set.</DD> +</DL> + +<H4> +Control Message Commands</H4> +Query commands result in NTP mode 7 packets containing requests for information +being sent to the server. These are read-only commands in that they make +no modification of the server configuration state. +<DL> +<DT> +<TT>listpeers</TT></DT> + +<DD> +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.</DD> + +<DT> +<TT>peers</TT></DT> + +<DD> +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 <TT>+</TT> denotes symmetric active, a <TT>-</TT> indicates +symmetric passive, a <TT>=</TT> means the remote server is being polled +in client mode, a <TT>^</TT> indicates that the server is broadcasting +to this address, a <TT>~</TT> denotes that the remote peer is sending broadcasts +and a <TT>*</TT> marks the peer the server is currently synchonizing to.</DD> + + +<P>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 <TT>REFCLK(<I>implementation number</I>, <I>parameter</I>)</TT>. +On <TT>hostnames no</TT> only IP-addresses will be displayed. +<DT> +<TT>dmpeers</TT></DT> + +<DD> +A slightly different peer summary list. Identical to the output of the +<TT>peers</TT> 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 <TT>.</TT> indicates that this peer +was cast off in the falseticker detection, while a <TT>+</TT> indicates +that the peer made it through. A <TT>*</TT> denotes the peer the server +is currently synchronizing with.</DD> + +<DT> +<TT>showpeer <I>peer_address</I> [...]</TT></DT> + +<DD> +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.</DD> + +<DT> +<TT>pstats <I>peer_address</I> [...]</TT></DT> + +<DD> +Show per-peer statistic counters associated with the specified peer(s).</DD> + +<DT> +<TT>clockinfo <I>clock_peer_address</I> [...]</TT></DT> + +<DD> +Obtain and print information concerning a peer clock. The values obtained +provide information on the setting of fudge factors and other clock performance +information.</DD> + +<DT> +<TT>kerninfo</TT></DT> + +<DD> +Obtain and print kernel phase-lock loop operating parameters. This information +is available only if the kernel has been specially modified for a precision +timekeeping function.</DD> + +<DT> +<TT>loopinfo [ oneline | multiline ]</TT></DT> + +<DD> +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 +<TT>offset</TT> is the last offset given to the loop filter by the packet +processing code. The <TT>frequency</TT> is the frequency error of the local +clock in parts-per-million (ppm). The <TT>time_const</TT> controls the +stiffness of the phase-lock loop and thus the speed at which it can adapt +to oscillator drift. The <TT>watchdog timer</TT> value is the number of +seconds which have elapsed since the last sample offset was given to the +loop filter. The <TT>oneline</TT> and <TT>multiline</TT> options specify +the format in which this information is to be printed, with <TT>multiline</TT> +as the default.</DD> + +<DT> +<TT>sysinfo</TT></DT> + +<DD> +Print a variety of system state variables, i.e., state related to the local +server. All except the last four lines are described in the NTP Version +3 specification, RFC-1305.</DD> + +<DL> +<DD> +The <TT>system flags</TT> show various system flags, some of which can +be set and cleared by the <TT>enable</TT> and <TT>disable</TT> configuration +commands, respectively. These are the <TT>auth</TT>, <TT>bclient</TT>, +<TT>monitor</TT>, <TT>pll</TT>, <TT>pps</TT> and <TT>stats</TT> flags. +See the <TT>ntpd</TT> documentation for the meaning of these flags. There +are two additional flags which are read only, the <TT>kernel_pll</TT> and +<TT>kernel_pps</TT>. These flags indicate the synchronization status when +the precision time kernel modifications are in use. The <TT>kernel_pll</TT> +indicates that the local clock is being disciplined by the kernel, while +the kernel_pps indicates the kernel discipline is provided by the PPS signal.</DD> + +<DD> +The <TT>stability</TT> is the residual frequency error remaining after +the system frequency correction is applied and is intended for maintenance +and debugging. In most architectures, this value will initially decrease +from as high as 500 ppm to a nominal value in the range .01 to 0.1 ppm. +If it remains high for some time after starting the daemon, something may +be wrong with the local clock, or the value of the kernel variable <TT>tick</TT> +may be incorrect.</DD> + +<DD> +The <TT>broadcastdelay</TT> shows the default broadcast delay, as set by +the <TT>broadcastdelay</TT> configuration command.</DD> + +<DD> +The <TT>authdelay</TT> shows the default authentication delay, as set by +the <TT>authdelay</TT> configuration command.</DD> +</DL> + +<DT> +<TT>sysstats</TT></DT> + +<DD> +Print statistics counters maintained in the protocol module.</DD> + +<DT> +<TT>memstats</TT></DT> + +<DD> +Print statistics counters related to memory allocation code.</DD> + +<DT> +<TT>iostats</TT></DT> + +<DD> +Print statistics counters maintained in the input-output module.</DD> + +<DT> +<TT>timerstats</TT></DT> + +<DD> +Print statistics counters maintained in the timer/event queue support code.</DD> + +<DT> +<TT>reslist</TT></DT> + +<DD> +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.</DD> + +<DT> +<TT>monlist [ <I>version</I> ]</TT></DT> + +<DD> +Obtain and print traffic counts collected and maintained by the monitor +facility. The version number should not normally need to be specified.</DD> + +<DT> +<TT>clkbug <I>clock_peer_address</I> [...]</TT></DT> + +<DD> +Obtain debugging information for a reference clock driver. This information +is provided only by some clock drivers and is mostly undecodable without +a copy of the driver source in hand.</DD> +</DL> + +<H4> +Runtime Configuration Requests</H4> +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 xtnpdc. This can be done using the keyid +and 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. + +<P>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. + +<P>The following commands all make authenticated requests. +<DL> +<DT> +<TT>addpeer <I>peer_address</I> [ <I>keyid</I> ] [ <I>version</I> ] [ <I>prefer</I> +]</TT></DT> + +<DD> +Add a configured peer association at the given address and operating in +symmetric active mode. 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. If the optional <TT>keyid</TT> +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 <TT>version#</TT> +can be 1, 2 or 3 and defaults to 3. The <TT>prefer</TT> 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.</DD> + +<DT> +<TT>addserver <I>peer_address</I> [ <I>keyid</I> ] [ <I>version</I> ] [ +<I>prefer</I> ]</TT></DT> + +<DD> +Identical to the addpeer command, except that the operating mode is client.</DD> + +<DT> +<TT>broadcast <I>peer_address</I> [ <I>keyid</I> ] [ <I>version</I> ] [ +<I>prefer</I> ]</TT></DT> + +<DD> +Identical to the addpeer command, except that the operating mode is broadcast. +In this case a valid key identifier and key are required. The <TT>peer_address</TT> +parameter can be the broadcast address of the local network or a multicast +group address assigned to NTP. If a multicast address, a multicast-capable +kernel is required.</DD> + +<DT> +<TT>unconfig <I>peer_address</I> [...]</TT></DT> + +<DD> +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.</DD> + +<DT> +<TT>fudge <I>peer_address</I> [ <I>time1</I> ] [ <I>time2</I> ] [ <I>stratum</I> +] [ <I>refid</I> ]</TT></DT> + +<DD> +This command provides a way to set certain data for a reference clock. +See the source listing for further information.</DD> + +<DT> +<TT>enable [ <I>flag</I> ] [ ... ]</TT></DT> + +<BR><TT>disable [ <I>flag</I> ] [ ... ]</TT> +<DD> +These commands operate in the same way as the <TT>enable</TT> and <TT>disable</TT> +configuration file commands of <TT>ntpd</TT>. Following is a description +of the flags. Note that only the <TT>auth</TT>, <TT>bclient</TT>, <TT>monitor</TT>, +<TT>pll</TT>, <TT>pps</TT> and <TT>stats</TT> flags can be set by <TT>ntpdc</TT>; +the <TT>pll_kernel</TT> and <TT>pps_kernel</TT> flags are read-only.</DD> + +<DL> +<DT> +<TT>auth</TT></DT> + +<DD> +Enables the server to synchronize with unconfigured peers only if the peer +has been correctly authenticated using a trusted key and key identifier. +The default for this flag is enable.</DD> + +<DT> +<TT>bclient</TT></DT> + +<DD> +Enables the server to listen for a message from a broadcast or multicast +server, as in the <TT>multicastclient</TT> command with default address. +The default for this flag is disable.</DD> + +<DT> +<TT>monitor</TT></DT> + +<DD> +Enables the monitoring facility. See the <TT>ntpdc</TT> program and the +<TT>monlist</TT> command or further information. The default for this flag +is enable.</DD> + +<DT> +<TT>pll</TT></DT> + +<DD> +Enables the server to adjust its local clock by means of NTP. If disabled, +the local clock free-runs at its intrinsic time and frequency offset. This +flag is useful in case the local clock is controlled by some other device +or protocol and NTP is used only to provide synchronization to other clients. +In this case, the local clock driver is used. See the <A HREF="refclock.htm">Reference +Clock Drivers </A>page for further information. The default for this flag +is enable.</DD> + +<DT> +<TT>pps</TT></DT> + +<DD> +Enables the pulse-per-second (PPS) signal when frequency and time is disciplined +by the precision time kernel modifications. See the <A HREF="kern.htm">A +Kernel Model for Precision Timekeeping </A>page for further information. +The default for this flag is disable.</DD> + +<DT> +<TT>stats</TT></DT> + +<DD> +Enables the statistics facility. See the <A HREF="monopt.htm">Monitoring +Options </A>page for further information. The default for this flag is +enable.</DD> + +<DT> +<TT>pll_kernel</TT></DT> + +<DD> +When the precision time kernel modifications are installed, this indicates +the kernel controls the clock discipline; otherwise, the daemon controls +the clock discipline.</DD> + +<DT> +<TT>pps_kernel</TT></DT> + +<DD> +When the precision time kernel modifications are installed and a pulse-per-second +(PPS) signal is available, this indicates the PPS signal controls the clock +discipline; otherwise, the daemon or kernel controls the clock discipline, +as indicated by the <TT>pll_kernel</TT> flag.</DD> +</DL> + +<DT> +<TT>restrict <I>address mask flag</I> [ <I>flag</I> ]</TT></DT> + +<DD> +This command operates in the same way as the <TT>restrict</TT> configuration +file commands of <TT>ntpd</TT>.</DD> + +<DT> +<TT>unrestrict <I>address mask flag</I> [ <I>flag</I> ]</TT></DT> + +<DD> +Unrestrict the matching entry from the restrict list.</DD> + +<DT> +<TT>delrestrict <I>address mask [ ntpport ]</I></TT></DT> + +<DD> +Delete the matching entry from the restrict list.</DD> + +<DT> +<TT>readkeys</TT></DT> + +<DD> +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 <TT>ntpd</TT> configuration file). This allows encryption keys to +be changed without restarting the server.</DD> + +<DT> +<TT>trustkey <I>keyid</I> [...]</TT></DT> + +<DT> +<TT>untrustkey <I>keyid</I> [...]</TT></DT> + +<DD> +These commands operate in the same way as the <TT>trustedkey</TT> and <TT>untrustkey</TT> +configuration file commands of <TT>ntpd</TT>.</DD> + +<DT> +<TT>authinfo</TT></DT> + +<DD> +Returns information concerning the authentication module, including known +keys and counts of encryptions and decryptions which have been done.</DD> + +<DT> +<TT>traps</TT></DT> + +<DD> +Display the traps set in the server. See the source listing for further +information.</DD> + +<DT> +<TT>addtrap [ <I>address</I> [ <I>port</I> ] [ <I>interface</I> ]</TT></DT> + +<DD> +Set a trap for asynchronous messages. See the source listing for further +information.</DD> + +<DT> +<TT>clrtrap [ <I>address</I> [ <I>port</I> ] [ <I>interface</I>]</TT></DT> + +<DD> +Clear a trap for asynchronous messages. See the source listing for further +information.</DD> + +<DT> +<TT>reset</TT></DT> + +<DD> +Clear the statistics counters in various modules of the server. See the +source listing for further information.</DD> +</DL> + +<H4> +Bugs</H4> +<TT>ntpdc</TT> 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. +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> |
