diff options
Diffstat (limited to 'contrib/ntp/html/ntpdc.htm')
| -rw-r--r-- | contrib/ntp/html/ntpdc.htm | 1181 |
1 files changed, 567 insertions, 614 deletions
diff --git a/contrib/ntp/html/ntpdc.htm b/contrib/ntp/html/ntpdc.htm index 52d1fdfe25bb..ffb2cc02732c 100644 --- a/contrib/ntp/html/ntpdc.htm +++ b/contrib/ntp/html/ntpdc.htm @@ -1,620 +1,573 @@ -<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> +<!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> -<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>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> -<DD> -Clear a trap for asynchronous messages. See the source listing for further -information.</DD> +<dt><tt>hostnames [ yes | no ]</tt></dt> -<DT> -<TT>reset</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> -<DD> -Clear the statistics counters in various modules of the server. See the -source listing for further information.</DD> -</DL> +<dt><tt>keyid <i>keyid</i></tt></dt> -<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> +<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> -</BODY> -</HTML> |