diff options
Diffstat (limited to 'contrib/ntp/html/ntpdc.htm')
| -rw-r--r-- | contrib/ntp/html/ntpdc.htm | 573 |
1 files changed, 0 insertions, 573 deletions
diff --git a/contrib/ntp/html/ntpdc.htm b/contrib/ntp/html/ntpdc.htm deleted file mode 100644 index ffb2cc0..0000000 --- a/contrib/ntp/html/ntpdc.htm +++ /dev/null @@ -1,573 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> -<html> -<head> -<meta name="generator" content="HTML Tidy, see www.w3.org"> -<title>ntpdc - special NTP query program</title> -</head> -<body> -<h3><tt>ntpdc</tt> - special NTP query program</h3> - -<img align="left" src="pic/alice31.gif" alt="gif"><a href= -"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's -Adventures in Wonderland</i>, Lewis Carroll</a> - -<p>This program is a big puppy.<br clear="left"> -</p> - -<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 startup using -ntpd's configuration file may also be specified at run time using -<tt>ntpdc</tt>. - -<p>If one or more request options are 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> - -<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> - -<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.</p> - -<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.</p> - -<dl> -<dt><tt>? [ <i>command_keyword</i> ]</tt><br> -<tt>help [ <i>command_keyword</i> ]</tt></dt> - -<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. - -<p>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.</p> - -<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.</p> -</dd> - -<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. - -<p>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.</p> - -<p>The <tt>stability</tt> is the residual frequency error remaining -afterthe 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.</p> - -<p>The <tt>broadcastdelay</tt> shows the default broadcast delay, -as set by the <tt>broadcastdelay</tt> configuration command.</p> - -<p>The <tt>authdelay</tt> shows the default authentication delay, -as set by the <tt>authdelay</tt> configuration command.</p> -</dd> - -<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> - -<p>The following commands all make authenticated requests.</p> - -<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><br> -<tt>disable [ <i>flag</i> ] [ ... ]</tt></dt> - -<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> - -<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> -</dd> - -<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>trustedkey <i>keyid</i> [...]</tt></dt> - -<dt><tt>untrustedkey <i>keyid</i> [...]</tt></dt> - -<dd>These commands operate in the same way as the <tt> -trustedkey</tt> and <tt>untrustedkey</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> -<a href="index.htm"><img align="left" src="pic/home.gif" alt= -"gif"></a> -<address><a href="mailto:mills@udel.edu">David L. Mills -<mills@udel.edu></a></address> -</body> -</html> - |
