distribution and storage.
<p>Authentication is configured separately for each association using
-the <tt>key</tt> or <tt>autokey</tt> subcommands on the <tt>peer</tt>,
+the <tt>key</tt> or autokey subcommands on the <tt>peer</tt>,
<tt>server</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> commands
-as described in the <A HREF="config.htm">Configuration Options</A> page.
+as described in the <a href=config.htm>Configuration Options</a> page.
The authentication options described below specify the suite of keys,
select the key for each configured association and manage the
configuration operations.
can be set or reset by the <tt>enable</tt> and <tt>disable</tt>
configuration commands and also by remote configuration commands sent by
a <tt>ntpdc</tt> program running in another machine. If this flag is
-enabled, new broadcast client and symmetric passive associations and
-remote configuration commands must be cryptographically authenticated
-using either symmetric-key or public-key schemes. If this flag is
-disabled, these operations are effective even if not cryptographic
-authenticated. It should be understood that operating in the latter mode
-invites a significant vulnerability where a rogue hacker can seriously
-disrupt client timekeeping.
+enabled, which is the default case, new broadcast client and symmetric
+passive associations and remote configuration commands must be
+cryptographically authenticated using either symmetric-key or public-key
+schemes. If this flag is disabled, these operations are effective even
+if not cryptographic authenticated. It should be understood that
+operating in the latter mode invites a significant vulnerability where a
+rogue hacker can seriously disrupt client timekeeping.
<p>In networks with firewalls and large numbers of broadcast clients it
may be acceptable to disable authentication, since that avoids key
are specified in a key file, usually called <tt>ntp.keys</tt>, which
should be exchanged and stored using secure procedures beyond the scope
of the NTP protocol itself. Besides the keys used for ordinary NTP
-associations, additional keys can be used as passwords for the <tt><A
-HREF="ntpq.htm">ntpq</A></tt> and <tt><A HREF="ntpdc.htm">ntpdc</A></tt>
+associations, additional keys can be used as passwords for the <tt><a
+href=ntpq.htm>ntpq</a></tt> and <tt><a href=ntpdc.htm>ntpdc</a></tt>
utility programs.
<p>When <tt>ntpd</tt> is first started, it reads the key file and
installs the keys in the key cache. However, the keys must be activated
-before they can be used with the <tt>trusted</tt> command. This allows,
-for instance, the installation of possibly several batches of keys and
-then activating or deactivating each batch remotely using
-<tt>ntpdc</tt>. This also provides a revocation capability that can be
-used if a key becomes compromised. The <tt>requestkey</tt> command
-selects the key used as the password for the <tt>ntpdc</tt> utility,
-while the <tt>controlkey</tt> command selects the key used as the
-password for the <tt>ntpq</tt> utility.
+with the <tt>trusted</tt> command before use. This allows, for instance,
+the installation of possibly several batches of keys and then activating
+or deactivating each batch remotely using <tt>ntpdc</tt>. This also
+provides a revocation capability that can be used if a key becomes
+compromised. The <tt>requestkey</tt> command selects the key used as the
+password for the <tt>ntpdc</tt> utility, while the <tt>controlkey</tt>
+command selects the key used as the password for the <tt>ntpq</tt>
+utility.
<h4>Public-Key Scheme</h4>
The original NTPv3 authentication scheme described in RFC-1305 continues
to be supported; however, in NTPv4 an additional authentication scheme
-called autokey is available. It uses MD5 message digest, RSA public-key
-signature and Diffie-Hellman key agreement algorithms available from
-several sources, but not included in the NTPv4 software distribution. In
-order to be effective, the <tt>rsaref20</tt> package must be installed
-as described in the <tt>README.rsa</tt> file. Once installed, the
-configure and build process automatically detects it and
+called <i>autokey</i> is available. It uses MD5 message digest, RSA
+public-key signature and Diffie-Hellman key agreement algorithms
+available from several sources, but not included in the NTPv4 software
+distribution. In order to be effective, the <tt>rsaref20</tt> package
+must be installed as described in the <tt>README.rsa</tt> file. Once
+installed, the configure and build process automatically detects it and
compiles the routines required.
The autokey scheme has several modes of operation corresponding to the
server. In symmetric modes the cookie is constructed using the
Diffie-Hellman key agreement algorithm. In other modes the cookie is
constructed from the IP addresses and a private value known only to the
-server. Multicast and symmetric modes use in addition a variant of the
-S-KEY scheme, in which a pseudo-random key list is generated and used in
-reverse order. These schemes are described along with an executive
-s
ummary, current status, briefing slides and reading list, on the <a
+server. All modes use in addition a variant of the S-KEY scheme, in
+which a pseudo-random key list is generated and used in reverse order.
+These schemes are described along with an executive summary, current
+status, briefing slides and reading list, on the <a
href=http://www.eecis.udel.edu/~mills/autokey.htm>Autonomous
Authentication</a> page.
<p>The cryptographic values used by the autokey scheme are incorporated
as a set of files generated by the <a
-href=genkeys.htm><tt>ntp_genkeys</tt></a> program, including the DES/MD5
-private keys, RSA public/private key pair, and the Diffie-Hellman
+href=genkeys.htm><tt>ntp_genkeys</tt></a> program, including the
+symmetric private keys, public/private key pair, and the agreement
parameters. See the <tt>ntp_genkeys</tt> page for a description of the
formats of these files. They contain cryptographic values generated by
the algorithms of the <tt>rsaref20</tt> package and are in printable
ASCII format. All file names include the timestamp, in NTP seconds,
following the default names given below. Since the file data are derived
from random values seeded by the system clock and the file name includes
-the timestamp, every generation produces a different file.
+the timestamp, every generation produces a different file and different
+file name.
-<p>The <tt>ntp.keys</tt> file contains the private DES/MD5 keys. It must
+<p>The <tt>ntp.keys</tt> file contains the DES/MD5 private keys. It must
be distributed by secure means to other servers and clients sharing the
same security compartment and made visible only to root. The
<tt>ntpkey</tt> file contains the RSA private key. It is useful only to
the machine that generated it and never shared with any other daemon or
-application program, so must be made visible only to root. The
-<tt>ntp_dh</tt> file contains the Diffie-Hellman parameters. It is
+application program, so must be made visible only to root.
+
+<p>The <tt>ntp_dh</tt> file contains the agreement parameters. It is
necessary that all servers and clients of a security compartment share a
-single <tt>ntp_dh</tt> file, but it does not matter which one. This file
-can be distributed using insecure means, since the data are public
-values.
+single set of parameters, but it does not matter which <tt>ntp_dh</tt>
+file generates them. The servers load the parameters directly from the
+file, while the clients load them indirectly from the servers using the
+autokey protocol. This file can be also be distributed using insecure
+means, since the data are public values.
<p>The <tt>ntpkey_<i>host</i></tt> file contains the RSA public key,
-where <tt><i>host</i></tt> is the name of the host. Each configured
-<tt>server</tt> or <tt>peer</tt> association requires the public key
-file associated with the particular server or peer to be installed at a
-default location or as specified by the commands below. In addition,
-public key files are required for all configured associations, including
+where <tt><i>host</i></tt> is the name of the host. Each <tt>server</tt>
+or <tt>peer</tt> association requires the public key associated with the
+particular server or peer to be loaded either directly from the file or
+indirectly from the server using the autokey protocol. In addition,
+public keys are required for all configured associations, including
those that might be mobilized by multicast servers or symmetric peers.
These files can be widely distributed and stored using insecure means,
since the data are public values.
<p>Due to the widespread use of interface-specific naming, the host
names used in configured and mobilized associations are determined by
the Unix <tt>gethostname()</tt> library routine. Both the
-<tt>ntp_genkeys</tt> program and the run-time protocol derive the name
-of the public key file using the name returned by this routine. While it
-is usually necessary to configure the private key file name and
-timestamp, the server and peer public file names are normally obtained
-directly from the server or peer.
+<tt>ntp_genkeys</tt> program and the autokey protocol derive the name of
+the public key file using the name returned by this routine. While every
+server and client is required to load their own public and private keys,
+the public keys for each client or peer association can be obtained from
+the server or peer using the autokey protocol. Note however, that at the
+current stage of development the authenticity of the server or peer and
+the cryptographic binding of the server name, address and public key is
+not yet established by a certificate authority or web of trust.
+Therefore, when the most secure requirements apply, the public keys and
+agreement parameters should be loaded from files, rather than using the
+autokey protocol.
<h4>Key Management</h4>
avoids installing them in each machine separately. The default can be
overridden by the <tt>keysdir</tt> configuration command. However, this
is not a good place to install the private key file, since each machine
-needs its own file. A suitable place to install it is <tt>/etc</tt>,
-which is normally not in a shared filesystem. The location can be
-overridden by the <tt>crypto</tt> configuration command.
-
-<p>All cryptographic keys and parameters should be regenerated on a
-periodic basis, like once per month. The <tt>ntp_genkeys</tt> program uses the same timestamp extension for all files generated at one time, so each generation is distinct and can be readily recognized. However, by default the file names expected by <tt>ntpd</tt> are without the timestamp extension. A simple approach to key maintenance is to distribute newly generated public files without the extension and install them in each server and client while in normal operation. This avoids the need to edit the NTP configuration file for each new generation.
-
-<p>A server and its clients load a new key generation in the following way. The server and its clients have loaded the old generation at startup and are operating normally. The new generation is installed at the server and its clients while the old generation is running. The server then restarts <tt>ntpd</tt> and loads the new generation, with result the clients no longer can authenticate. After a few minutes the clients time out and restart the protocol from the beginning, with result the new generation is loaded and operation continues normally.
-
-<p>Key distribution can be done semi-automatically using a set of shell scripts and the Unix <tt>rdist</tt> utility. Each server runs the <tt>ntp_genkeys</tt> program from a <tt>cron</tt> job, and uploads the relevant public files to a common location accessible to the <tt>rdist</tt> utility. At that location a script selects one of the Diffie-Hellman files and bundles it along with the latest generation of public-key files for <tt>rdist</tt>, which downloads them to all servers and clients.
+needs its own file. A suitable place to install it is in <tt>/etc</tt>,
+which is normally not in a shared filesystem.
+
+<p>The recommended practice is to keep the timestamp extensions when
+installing a file and to install a link from the default name (without
+the timestamp extension) to the actual file. This allows new file
+generations to be activated simply by changing the link. However,
+<tt>ntpd</tt> parses the link name when present to extract the extension
+value and sends it along with the public key and host name when
+requested. This allows clients to verify that the file and generation
+time are always current. However, the actual location of each file can
+be overridden by the <tt>crypto</tt> configuration command.
+
+<p>All cryptographic keys and related parameters should be regenerated
+on a periodic and automatic basis, like once per month. The
+<tt>ntp_genkeys</tt> program uses the same timestamp extension for all
+files generated at one time, so each generation is distinct and can be
+readily recognized in monitoring data. While a public/private key pair
+must be generated by every server and client, the public keys and
+agreement parameters do not need to be explicitly copied to all machines
+in the same security compartment, since they can be obtained
+automatically using the autokey protocol. However, it is necessary that
+all primary servers have the same agreement parameter file. The
+recommended way to do this is for one of the primary servers to generate
+that file and then copy it to the other primary servers in the same
+compartment using the Unix <tt>rdist</tt> command. Future versions of
+the autokey protocol are to contain provisions for an agreement protocol
+to do this automatically.
+
+<p>Servers and clients can make a new generation in the following way.
+All machines have loaded the old generation at startup and are operating
+normally. At designated intervals, each machine generates a new
+public/private key pair and makes links from the default file names to
+the new file names. The <tt>ntpd</tt> is then restarted and loads the
+new generation, with result clients no longer can authenticate
+correctly. The autokey protocol is designed so that after a few minutes
+the clients time out and restart the protocol from the beginning, with
+result the new generation is loaded and operation continues as before. A
+similar procedure can be used for the agreement parameter file, but in
+this case precautions must be take to be sure that all machines with
+this file have the same copy.
<h4>Authentication Commands</h4>
<dt><tt>autokey [<i>logsec</i>]</tt>
<dd>Specifies the interval between regenerations of the session key list
-used with the autokey feature. Note that the size of the key list for
+used with the autokey protocol. Note that the size of the key list for
each association depends on this interval and the current poll interval.
The default value is 12 (4096 s or about 1.1 hours). For poll intervals
above the specified interval, a session key list with a single entry
will be regenerated for every message sent.</dd>
<dt><tt>controlkey <i>key</i></tt></dt>
-<dd>Specifies the key identifier to use with the <tt>ntpq</tt> program,
-which uses the standard protocol defined in RFC-1305. This program is
-useful to diagnose and repair problems that affect <tt>ntpd</tt>
-operation. The <tt><i>key</i></tt> argument to this command is a key
-identifier for a trusted key, where the value can be in the range 1 to
-65534, inclusive.</dd>
+<dd>Specifies the key identifier to use with the <a
+href=ntpq.htm><tt>ntpq</tt></a> utility, which uses the standard
+protocol defined in RFC-1305. The <tt><i>key</i></tt> argument is the
+key identifier for a trusted key, where the value can be in the range 1
+to 65534, inclusive.</dd>
<dt><tt>crypto [privatekey <i>file</i>] [publickey <i>file</i>] [dhparms
<i>file</i>] </tt></dt>
<dd>This command requires the NTP daemon build process be configured
-with the RSA library. The presence of this command causes the daemon to
-load the host RSA private key file, public key file and Diffie-Hellman
-parameter file. If one or more files are left unspecified, the default
-names are used as described above. Following are the subcommands:</dd>
+with the RSA library. This command activates public-key cryptography and
+loads the required RSA private and public key files and the optional
+Diffie-Hellman agreement parameter file, if present. If one or more
+files are left unspecified, the default names are used as described
+below. Following are the subcommands:</dd>
<dl>
<dt><tt>privatekey <i>file</tt></i>
-<dd>Specifies the directory for the RSA private key file, which
-otherwise defaults to <tt>/usr/local/etc</tt>.</dd>
+<dd>Specifies the location of the RSA private key file, which
+otherwise defaults to <tt>/usr/local/etc/ntpkey</tt>.</dd>
<dt><tt>publickey <i>file</tt></i>
-<dd>Specifies the directory for the RSA public key file, which otherwise
-defaults to <tt>/usr/local/etc</tt>.</dd>
+<dd>Specifies the location of the RSA public key file, which otherwise
+defaults to <tt>/usr/local/etc/ntpkey_<i>host</i></tt>., where
+<i>host</i> is the name of the generating machine.</dd>
<dt><tt>dhparms <i>file</tt></i>
-<dd>Specifies the directory for the Diffie-Hellman parameters file,
-which otherwise defaults to <tt>/usr/local/etc</tt>.</dd>
+<dd>Specifies the location of the Diffie-Hellman parameters file,
+which otherwise defaults to <tt>/usr/local/etc/ntpkey_dh</tt>.</dd>
</dl>
<dt><tt>keys <i>keyfile</i></tt></dt>
-<dd>Specifies the file name containing the private encryption keys and
-key identifiers used by <tt>ntpd</tt>, <tt>ntpq</tt> and <tt>ntpdc</tt>
-when operating in authenticated mode.</dd>
+<dd>Specifies the location of the DES/MD5 private key file containing
+the keys and key identifiers used by <tt>ntpd</tt>, <tt>ntpq</tt> and
+<tt>ntpdc</tt> when operating in symmetric-key mode.</dd>
<dt><tt>keysdir <i>path</i></tt></dt>
<dd>This command requires the NTP daemon build process be configured
with the RSA library. It specifies the default directory path for the
-private key file, parameters file and one or more public key files. The
-default when this command does not appear in the configuration file is
-<tt>/usr/local/etc/</tt>.</dd>
+private key file, agreement parameters file and one or more public key
+files. The default when this command does not appear in the
+configuration file is <tt>/usr/local/etc/</tt>.</dd>
<dt><tt>requestkey <i>key</i></tt></dt>
-<dd>Specifies the key identifier to use with the <tt>ntpdc</tt> utility
-program, which uses a proprietary protocol specific to this
-implementation of <tt>ntpd</tt>. This program is useful to diagnose and
-repair problems that affect <tt>ntpd</tt> operation. The
-<tt><i>key</i></tt> argument to this command is a key identifier for a
-trusted key, where the value can be in the range 1 to 65534, inclusive.
-</dd>
+<dd>Specifies the key identifier to use with the <a
+href=ntpdc.htm><tt>ntpdc</tt></a> utility program, which uses a
+proprietary protocol specific to this implementation of <tt>ntpd</tt>.
+The <tt><i>key</i></tt> argument is a key identifier for the trusted
+key, where the value can be in the range 1 to 65534, inclusive.</dd>
<dt><tt>revoke [<i>logsec</i>]</tt>
<dd>Specifies the interval between re-randomization of certain
interval, the values will be updated for every message sent.</dd>
<dt><tt>trustedkey <i>key</i> [...]</tt></dt>
-<dd>Specifies the encryption key identifiers which are trusted for the
-purposes of authenticating peers suitable for synchronization, as well
-as keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> programs. The
+<dd>Specifies the key identifiers which are trusted for the purposes of
+authenticating peers with symmetric-key cryptography, as well as keys
+used by the <tt>ntpq</tt> and <tt>ntpdc</tt> programs. The
authentication procedures require that both the local and remote servers
share the same key and key identifier for this purpose, although
different keys can be used with different servers. The
<tt>ntp.keys</tt> private MD5 keys
<br><tt>ntpkey</tt> RSA private key
<br><tt>ntpkey_<i>host</i></tt> RSA public key
-<br><tt>ntp_dh</tt> Diffie-Hellman parameters
+<br><tt>ntp_dh</tt> Diffie-Hellman agreement parameters
<h4>Bugs</h4>
-<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>ntpq - standard NTP query program
-</TITLE>
-</HEAD>
-<BODY>
-
-<H3>
-<TT>pq</TT> - standard NTP query program</H3>
-
-<HR>
-<H4>
-Synopsis</H4>
-<TT>ntpq [-inp] [-c <I>command</I>] [<I>host</I>] [...]</TT>
-<H4>
-Description</H4>
-<TT>ntpq</TT> is used to query NTP servers which implement the recommended
-NTP mode 6 control message format about current state and to request changes
-in that state. The program may be run either in interactive mode or controlled
-using command line arguments. Requests to read and write arbitrary variables
-can be assembled, with raw and pretty-printed output options being available.
-<TT>ntpq</TT> can also obtain and print a list of peers in a common format
-by sending multiple queries to the server.
-
-<P>If one or more request options is included on the command line when
-<TT>ntpq</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>ntpq</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>ntpq</TT>
-will prompt for commands if the standard input is a terminal device.
-
-<P><TT>ntpq</TT> uses NTP mode 6 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>ntpq</TT> makes one attempt to retransmit requests, and will
-time requests out if the remote host is not heard from within a suitable
+<html><head><title>
+ntpq - standard NTP query program
+</title></head><body><h3>
+<tt>ntpq</tt> - standard NTP query program
+</h3><HR>
+
+<h4>Synopsis</h4>
+
+<tt>ntpq [-inp] [-c <i>command</i>] [<i>host</i>] [...]</tt>
+
+<h4>Description</h4>
+
+The <tt>ntpq</tt> utility program is used to query NTP servers which implement the recommended NTP mode 6 control message format about current state and to request changes in that state. The program may be run either in interactive mode or controlled using command line arguments. Requests to read and write arbitrary variables can be assembled, with raw and pretty-printed output options being available. <tt>ntpq</tt> can also obtain and print a list of peers in a common format by sending multiple queries to the server.
+
+<p>If one or more request options is included on the command line when <tt>ntpq</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>ntpq</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>ntpq</tt>will prompt for commands if the standard input is a terminal device.
+
+<p><tt>ntpq</tt> uses NTP mode 6 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>ntpq</tt> makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable
timeout time.
-<P>Command line options are described following. Specifying a command line
-option other than -i or -n will cause the specified query (queries) to
-be sent to the indicated host(s) immediately. Otherwise, <TT>ntpq</TT>
-will attempt to read interactive format commands from the standard input.
-<DL>
-<DT>
-<TT>-c</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>ntpq</TT> to operate in interactive mode. Prompts will be written
-to the standard output and commands read from the standard input.</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 the <TT>peers</TT> interactive command.</DD>
-</DL>
-
-<H4>
-Internal 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 "<", followed by a file name, to the
-command line. A number of interactive format commands are executed entirely
-within the <TT>ntpq</TT> program itself and do not result in NTP mode 6
-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>
-
-<DD>
- </DD>
-
-<DT>
-<TT>addvars <I>variable_name</I> [ = <I>value</I>] [...]</TT></DT>
-
-<BR><TT>rmvars <I>variable_name</I> [...]</TT>
-<BR><TT>clearvars</TT>
-<DD>
-The data carried by NTP mode 6 messages consists of a list of items of
-the form <TT><I>variable_name</I> = <I>value</I></TT>, where the <TT>"
-= <I>value</I>"</TT> is ignored, and can be omitted, in requests to the
-server to read variables. <TT>ntpq</TT> maintains an internal list in which
-data to be included in control messages can be assembled, and sent using
-the readlist and writelist commands described below. The addvars command
-allows variables and their optional values to be added to the list. If
-more than one variable is to be added, the list should be comma-separated
-and not contain white space. The rmvars command can be used to remove individual
-variables from the list, while the clearlist command removes all variables
-from the list.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>authenticate yes | no</TT></DT>
-
-<DD>
-Normally <TT>ntpq</TT> does not authenticate requests unless they are write
-requests. The command authenticate yes causes <TT>ntpq</TT> to send authentication
-with all requests it makes. Authenticated requests causes some servers
-to handle requests slightly differently, and can occasionally melt the
-CPU in fuzzballs if you turn authentication on before doing a peer display.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>cooked</TT></DT>
-
-<DD>
-Causes output from query commands to be <TT>"cooked"</TT>. Variables which
-are recognized by the server will have their values reformatted for human
-consumption. Variables which <TT>ntpq</TT> thinks should have a decodeable
-value but didn't are marked with a trailing <TT>"?"</TT>.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>debug more | less | off</TT></DT>
-
-<DD>
-Turns internal query program debugging on and off.</DD>
-
-<DD>
- </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>
-
-<DD>
- </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>
- </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>
-
-<DD>
- </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>
-
-<DD>
- </DD>
-
-<DT>
-<TT>ntpversion 1 | 2 | 3 | 4</TT></DT>
-
-<DD>
-Sets the NTP version number which <TT>ntpq</TT> claims in packets. Defaults
-to 3, Note that mode 6 control messages (and modes, for that matter) didn't
-exist in NTP version 1. There appear to be no servers left which demand
-version 1.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>quit</TT></DT>
-
-<DD>
-Exit <TT>ntpq</TT>.</DD>
-
-<DD>
- </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>
-
-<DD>
- </DD>
-
-<DT>
-<TT>raw</TT></DT>
-
-<DD>
-Causes all output from query commands is printed as received from the remote
-server. The only formating/intepretation done on the data is to transform
-nonascii data into a printable (but barely understandable) form.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>timeout <I>millseconds</I></TT></DT>
-
-<DD>
-Specify a timeout period for responses to server queries. The default is
-about 5000 milliseconds. Note that since <TT>ntpq</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>
-Each peer known to an NTP server has a 16 bit integer association identifier
-assigned to it. NTP control messages which carry peer variables must identify
-the peer the values correspond to by including its association ID. An association
-ID of 0 is special, and indicates the variables are system variables, whose
-names are drawn from a separate name space.
-
-<P>Control message commands result in one or more NTP mode 6 messages being
-sent to the server, and cause the data returned to be printed in some format.
-Most commands currently implemented send a single message and expect a
-single response. The current exceptions are the peers command, which will
-send a preprogrammed series of messages to obtain the data it needs, and
-the mreadlist and mreadvar commands, which will iterate over a range of
-associations.
-<DL>
-<DT>
-<TT>associations</TT></DT>
-
-<DD>
-Obtains and prints a list of association identifiers and peer statuses
-for in-spec peers of the server being queried. The list is printed in columns.
-The first of these is an index numbering the associations from 1 for internal
-use, the second the actual association identifier returned by the server
-and the third the status word for the peer. This is followed by a number
-of columns containing data decoded from the status word See the peers command
-for a decode of the <TT>condition</TT> field. Note that the data returned
-by the <TT>"associations"</TT> command is cached internally in <TT>ntpq</TT>.
-The index is then of use when dealing with stupid servers which use association
-identifiers which are hard for humans to type, in that for any subsequent
-commands which require an association identifier as an argument, the form
-and index may be used as an alternative.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>clockvar [<I>assocID</I>] [<I>variable_name</I> [ = <I>value</I> [...]
-] [...]</TT></DT>
-
-<DT>
-<TT>cv [<I>assocID</I>] [<I>variable_name</I> [ = <I>value</I> [...] ]
-[...]</TT></DT>
-
-<DD>
-Requests that a list of the server's clock variables be sent. Servers which
-have a radio clock or other external synchronization will respond positively
-to this. If the association identifier is omitted or zero the request is
-for the variables of the <TT>"system clock"</TT> and will generally get
-a positive response from all servers with a clock. If the server treats
-clocks as pseudo-peers, and hence can possibly have more than one clock
-connected at once, referencing the appropriate peer association ID will
-show the variables of a particular clock. Omitting the variable list will
-cause the server to return a default variable display.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>lassocations</TT></DT>
-
-<DD>
-Obtains and prints a list of association identifiers and peer statuses
-for all associations for which the server is maintaining state. This command
-differs from the <TT>"associations"</TT> command only for servers which
-retain state for out-of-spec client associations (i.e., fuzzballs). Such
-associations are normally omitted from the display when the <TT>"associations"</TT>
-command is used, but are included in the output of <TT>"lassociations"</TT>.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>lpassociations</TT></DT>
-
-<DD>
-Print data for all associations, including out-of-spec client associations,
-from the internally cached list of associations. This command differs from
-<TT>"passociations"</TT> only when dealing with fuzzballs.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>lpeers</TT></DT>
-
-<DD>
-Like R peers, except a summary of all associations for which the server
-is maintaining state is printed. This can produce a much longer list of
-peers from fuzzball servers.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>mreadlist <I>assocID</I> <I>assocID</I></TT></DT>
-
-<BR><TT>mrl <I>assocID</I> <I>assocID</I></TT>
-<DD>
-Like the <TT>readlist</TT> command, except the query is done for each of
-a range of (nonzero) association IDs. This range is determined from the
-association list cached by the most recent <TT>associations</TT> command.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>mreadvar <I>assocID</I> <I>assocID</I> [ <I>variable_name</I> [ = <I>value</I>
-[ ... ]</TT></DT>
-
-<BR><TT>mrv <I>assocID</I> <I>assocID</I> [ <I>variable_name</I> [ = <I>value</I>
-[ ... ]</TT>
-<DD>
-Like the <TT>readvar</TT> command, except the query is done for each of
-a range of (nonzero) association IDs. This range is determined from the
-association list cached by the most recent <TT>associations</TT> command.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>opeers</TT></DT>
-
-<DD>
-An old form of the <TT>peers</TT> command with the reference ID replaced
-by the local interface address.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>passociations</TT></DT>
-
-<DD>
-Prints association data concerning in-spec peers from the internally cached
-list of associations. This command performs identically to the <TT>"associations"</TT>
-except that it displays the internally stored data rather than making a
-new query.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>peers</TT></DT>
-
-<DD>
-Obtains a current list peers of the server, along with a summary of each
-peer's state. Summary information includes the address of the remote peer,
-the reference ID (0.0.0.0 if this is unknown), the stratum of the remote
-peer, the type of the peer (local, unicast, multicast or broadcast), when
-the last packet was received, the polling interval, in seconds, the reachability
-register, in octal, and the current estimated delay, offset and dispersion
-of the peer, all in milliseconds.</DD>
+<p>Command line options are described following. 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>ntpq</tt> will attempt to read interactive format commands from the standard input.
+
+<dl>
+
+<dt><tt>-c</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 <tt>-c</tt> options may be given.</dd>
+
+<dt><tt>-i</tt></dt>
+<dd>Force <tt>ntpq</tt> to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.</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 the <tt>peers</tt> interactive command.</dd>
+
+</dl>
+
+<h4>Internal 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. A number of interactive format commands are executed entirely within the <tt>ntpq</tt> program itself and do not result in NTP mode 6 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>addvars <i>variable_name</i> [ = <i>value</i>] [...]</tt></dt>
+<BR><tt>rmvars <i>variable_name</i> [...]</tt>
+<BR><tt>clearvars</tt>
+<dd>The data carried by NTP mode 6 messages consists of a list of items of the form <tt><i>variable_name</i> = <i>value</i></tt>, where the <tt> = <i>value</i></tt> is ignored, and can be omitted, in requests to the server to read variables. <tt>ntpq</tt> maintains an internal list in which data to be included in control messages can be assembled, and sent using the <tt>readlist</tt> and <tt>writelist</tt> commands described below. The <tt>addvars</tt> command allows variables and their optional values to be added to the list. If more than one variable is to be added, the list should be comma-separated and not contain white space. The <tt>rmvars</tt> command can be used to remove individual variables from the list, while the <tt>clearlist</tt> command removes all variables from the list.</dd>
+
+<dt><tt>authenticate yes | no</tt></dt>
+<dd>Normally <tt>ntpq</tt> does not authenticate requests unless they are write requests. The command <tt>authenticate yes</tt> causes <tt>ntpq</tt> to send authentication with all requests it makes. Authenticated requests causes some servers to handle requests slightly differently, and can occasionally melt the CPU in fuzzballs if you turn authentication on before doing a <tt>peer</tt> display. [I didn't know that - Ed.]</dd>
+
+<dt><tt>cooked</tt></dt>
+<dd>Causes output from query commands to be "cooked", so that variables which are recognized by <tt>ntpq</tt> will have their values reformatted for human consumption. Variables which <tt>ntpq</tt> thinks should have a decodeable value but didn't are marked with a trailing <tt>?</tt>.</dd>
+
+<dt><tt>debug more | less | off</tt></dt>
+<dd>Turns internal query program debugging on and off.</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>ntpversion 1 | 2 | 3 | 4</tt></dt>
+<dd>Sets the NTP version number which <tt>ntpq</tt> claims in packets. Defaults to 3, Note that mode 6 control messages (and modes, for that matter) didn't exist in NTP version 1. There appear to be no servers left which demand version 1.</dd>
+
+<dt><tt>quit</tt></dt>
+<dd>Exit <tt>ntpq</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>raw</tt></dt>
+<dd>Causes all output from query commands is printed as received from the remote server. The only formating/intepretation done on the data is to transform nonascii data into a printable (but barely understandable) form.</dd>
+
+<dt><tt>timeout <i>millseconds</i></tt></dt>
+<dd>Specify a timeout period for responses to server queries. The default is about 5000 milliseconds. Note that since <tt>ntpq</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>
+
+Each peer known to an NTP server has a 16 bit integer association identifier assigned to it. NTP control messages which carry peer variables must identify the peer the values correspond to by including its association ID. An association ID of 0 is special, and indicates the variables are system variables, whose names are drawn from a separate name space.
+
+<p>Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to be printed in some format. Most commands currently implemented send a single message and expect a single response. The current exceptions are the peers command, which will send a preprogrammed series of messages to obtain the data it needs, and the mreadlist and mreadvar commands, which will iterate over a range of associations.
+
+<dl>
+
+<dt><tt>associations</tt></dt>
+
+<dd>Obtains and prints a list of association identifiers and peer statuses for in-spec peers of the server being queried. The list is printed in columns. The first of these is an index numbering the associations from 1 for internal use, the second the actual association identifier returned by the server and the third the status word for the peer. This is followed by a number of columns containing data decoded from the status word See the peers command for a decode of the <tt>condition</tt> field. Note that the data returned by the <tt>associations"</tt> command is cached internally in <tt>ntpq</tt>. The index is then of use when dealing with stupid servers which use association identifiers which are hard for humans to type, in that for any subsequent commands which require an association identifier as an argument, the form and index may be used as an alternative.</dd>
+
+<dt><tt>clockvar [<i>assocID</i>] [<i>variable_name</i> [ = <i>value</i> [...]] [...]</tt></dt>
+
+<dt><tt>cv [<i>assocID</i>] [<i>variable_name</i> [ = <i>value</i> [...] ][...]</tt></dt>
+<dd>Requests that a list of the server's clock variables be sent. Servers which have a radio clock or other external synchronization will respond positively to this. If the association identifier is omitted or zero the request is for the variables of the <tt>system clock</tt> and will generally get a positive response from all servers with a clock. If the server treats clocks as pseudo-peers, and hence can possibly have more than one clock connected at once, referencing the appropriate peer association ID will show the variables of a particular clock. Omitting the variable list will cause the server to return a default variable display.</dd>
+
+<dt><tt>lassocations</tt></dt>
+<dd>Obtains and prints a list of association identifiers and peer statuses for all associations for which the server is maintaining state. This command differs from the <tt>associations</tt> command only for servers which retain state for out-of-spec client associations (i.e., fuzzballs). Such associations are normally omitted from the display when the <tt>associations</tt> command is used, but are included in the output of <tt>lassociations</tt>.</dd>
+
+<dt><tt>lpassociations</tt></dt>
+<dd>Print data for all associations, including out-of-spec client associations, from the internally cached list of associations. This command differs from <tt>passociations</tt> only when dealing with fuzzballs.</dd>
+
+<dt><tt>lpeers</tt></dt>
+<dd>Like R peers, except a summary of all associations for which the server is maintaining state is printed. This can produce a much longer list of peers from fuzzball servers.</dd>
+
+<dt><tt>mreadlist <i>assocID</i> <i>assocID</i></tt></dt>
+<BR><tt>mrl <i>assocID</i> <i>assocID</i></tt>
+<dd>Like the <tt>readlist</tt> command, except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent <tt>associations</tt> command.</dd>
+
+<dt><tt>mreadvar <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i>[ ... ]</tt></dt>
+<BR><tt>mrv <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i>[ ... ]</tt>
+<dd>Like the <tt>readvar</tt> command, except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent <tt>associations</tt> command.</dd>
+
+<dt><tt>opeers</tt></dt>
+<dd>An old form of the <tt>peers</tt> command with the reference ID replaced by the local interface address.</dd>
+
+<dt><tt>passociations</tt></dt>
+<dd>Displays association data concerning in-spec peers from the internally cached list of associations. This command performs identically to the <tt>associations</tt> except that it displays the internally stored data rather than making a new query.</dd>
+
+<dt><tt>peers</tt></dt>
+<dd>Obtains a current list peers of the server, along with a summary of each peer's state. Summary information includes the address of the remote peer, the reference ID (0.0.0.0 if this is unknown), the stratum of the remote peer, the type of the peer (local, unicast, multicast or broadcast), when the last packet was received, the polling interval, in seconds, the reachability register, in octal, and the current estimated delay, offset and dispersion of the peer, all in milliseconds.</dd>
+
+<dd>The character in the left margin indicates the fate of this peer in the clock selection process. Folowing is a list of these characters, the pidgeon used in the <tt>rv</tt> command, and a short explanation of the condition revealed.</dd>
-<DD>
- </DD>
-
-<DD>
-The character in the left margin indicates the fate of this peer in the
-clock selection process. Folowing is a list of these characters, the pidgeon
-used in the <TT>rv</TT> command, and a short explanation of the condition
-revealed.</DD>
-
-<DD>
- </DD>
-
-<DD>
-<TT>space reject</TT></DD>
+<dl>
-<DL>
-<DD>
-The peer is discarded as unreachable, synchronized to this server (synch
-loop) or outrageous synchronization distance.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>x falsetick</TT></DD>
-
-<DL>
-<DD>
-The peer is discarded by the intersection algorithm as a falseticker.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>. excess</TT></DD>
-
-<DL>
-<DD>
-The peer is discarded as not among the first ten peers sorted by synchronization
-distance and so is probably a poor candidate for further consideration.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>- outlyer</TT></DD>
-
-<DL>
-<DD>
-The peer is discarded by the clustering algorithm as an outlyer.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>+ candidat</TT></DD>
-
-<DL>
-<DD>
-The peer is a survivor and a candidate for the combining algorithm.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT># selected</TT></DD>
-
-<DL>
-<DD>
-The peer is a survivor, but not among the first six peers sorted by synchronization
-distance. If the assocation is ephemeral, it may be demobilized to conserve
-resources.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>* sys.peer</TT></DD>
-
-<DL>
-<DD>
-The peer has been declared the system peer and lends its variables to the
-system variables.</DD>
-</DL>
-
-<DD>
-<TT> </TT></DD>
-
-<DD>
-<TT>o pps.peer</TT></DD>
-
-<DL>
-<DD>
-The peer has been declared the system peer and lends its variables to the
-system variables. However, the actual system synchronization is derived
-from a pulse-per-second (PPS) signal, either indirectly via the PPS reference
-clock driver or directly via kernel interface.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-The <TT>flash</TT> variable is not defined in the NTP specification, but
-is included as a valuable debugging aid. It displays the results of the
-packet sanity checks defined in the NTP specification <TT>TEST1</TT> through
-<TT>TEST9</TT>. The bits for each test read in increasing sequency from
-the least significant bit and are defined as follows.</DD>
-
-<DD>
- </DD>
-
-<DD>
-The following <TT>TEST1</TT> through <TT>TEST4</TT> enumerate procedure
-errors. The packet timestamps may or may not be believed, but the remaining
-header data are ignored.</DD>
+<dt><tt>space reject</tt></dt>
+<dd>The peer is discarded as unreachable, synchronized to this server (synch loop) or outrageous synchronization distance.</dd>
+
+<dt><tt>x falsetick</tt></dt>
+<dd>The peer is discarded by the intersection algorithm as a falseticker.</dd>
+
+<dt><tt>. excess</tt></dt>
+<dd>The peer is discarded as not among the first ten peers sorted by synchronization distance and so is probably a poor candidate for further consideration.</dd>
+
+<dt><tt>- outlyer</tt></dt>
+<dd>The peer is discarded by the clustering algorithm as an outlyer.</dd>
+
+<dt><tt>+ candidat</tt></dt>
+<dd>The peer is a survivor and a candidate for the combining algorithm.</dd>
+
+<dt><tt># selected</tt></dt>
+<dd>The peer is a survivor, but not among the first six peers sorted by synchronization distance. If the assocation is ephemeral, it may be demobilized to conserve resources.</dd>
+
+<dt><tt>* sys.peer</tt></dt>
+<dd>The peer has been declared the system peer and lends its variables to the system variables.</dd>
+
+<dt><tt>o pps.peer</tt></dt>
+<dd>The peer has been declared the system peer and lends its variables to thesystem variables. However, the actual system synchronization is derived from a pulse-per-second (PPS) signal, either indirectly via the PPS reference clock driver or directly via kernel interface.</dd>
+
+</dl>
+
+<p><dd>The <tt>flash</tt> variable is not defined in the NTP specification, but is included as a valuable debugging aid. It displays the results of the original sanity checks defined in the NTP specification RFC-1305 and additional ones added since then. There are eleven tests named <tt>TEST1</tt> through <tt>TEST11</tt>. Tests <tt>TEST1</tt> through <tt>TEST5</tt> represent checks on the basic header data from which the offset and delay are calculated. If any of these tests fail, the packet is discarded without further processing. Tests <tt>TEST6</tt> through <tt>TEST9</tt> represent checks on the remaining header values. Tests <tt>TEST10</tt> and <tt>TEST11</tt> represent checks using public key cryptography. They have meaning only if support for the autokey public key support has been configured in the system. If any of these tests fail, the basic header data are captured, but the packet is then discarded. The bits for each test read in increasing order from the least significant bit are defined as follows.</dd>
+
+<p><dd>The following <tt>TEST1</tt> through <tt>TEST4</tt> enumerate procedure errors. The packet timestamps may or may not be believed, but the remaining header data are ignored.</dd>
+
+<dl>
+
+<dt><tt>TEST1</tt></dt>
+<dd>Duplicate packet. The packet is at best a casual retransmission and at worst a malicious replay.</dd>
+
+<dt><tt>TEST2</tt></dt>
+<dd>Bogus packet. The packet is not a reply to a message previously sent. This can happen when the NTP daemon is restarted and before somebody else notices.</dd>
+
+<dt><tt>TEST3</tt></dt>
+<dd>Unsynchronized. One or more timestamp fields are invalid. This normally happens when the first packet from a peer is received.</dd>
+
+<dt><tt>TEST4</tt></dt>
+<dd>Access is denied. See the <A HREF="accopt.htm">Access Control Options</A> page.</dd>
+
+<dt><tt>TEST5</tt></dt>
+<dd>Cryptographic authentication fails. See the <A HREF="authopt.htm">Authentication Options</A> page.</dd>
+
+<dt><tt>TEST6</tt></dt>
+<dd>The server is unsynchronized. Wind up its clock first.</dd>
+
+<dt><tt>TEST7</tt></dt>
+<dd>The server stratum is greater than 15. It is probably unsynchronized and its clock needs to be wound up.</dd>
+
+<dt><tt>TEST8</tt></dt>
+<dd>Either the root delay or dispersion is greater than one second, which is highly unlikely unless the peer is synchronized to Mars.</dd>
+
+<dt><tt>TEST9</tt></dt>
+<dd>Either the peer delay or dispersion is greater than one second, which is higly unlikely unless the peer is on Mars.</dd>
+
+<dt><tt>TEST10</tt></dt>
+<dd>The autokey protocol has detected an authentication failure. See the <A HREF="authopt.htm">Authentication Options</A> page.</dd>
+
+<dt><tt>TEST11</tt></dt>
+<dd>The autokey protocol has not verified the server or peer is authentic with public key credentials. See the <A HREF="authopt.htm">Authentication Options</A> page.</dd>
+
+</dl>
+
+<p><dd>Additional system variables not defined in the NTP specification
+RFC-1305 are used by the autokey public key support. They include the following:
+
+<dl>
+
+<dt><tt>privatekey <i>filename</i></tt>/<dt>
+<dd>Specifies the name of the RSA private key file.</dd>
+
+<dt><tt>publickey <i>filename</i></tt>/<dt>
+<dd>Specifies the name of the RSA public key file.</dd>
+
+<dt><tt>dhparams <i>filename</i></tt>/<dt>
+<dd>Specifies the name of the Diffie-Hellman parameter file.</dd>
+
+<dt><tt>hostname <i>host</i></tt>/<dt>
+<dd>Specifies the name of the host.</dd>
+
+<dt><tt>revoketime <i>host</i></tt>/<dt>
+<dd>Specifies the last time the public and private values used in the agreement algorithm were refreshed.</dd>
+
+</dl>
+
+<p><dd>Additional peer variables not defined in the NTP specification
+RFC-1305 are used by the autokey public key support. They include the following:
+
+<dl>
+
+<dt><tt>pcookie <i>hex</i></tt>/<dt>
+<dd>Specifies the peer cookie used in the key agreement algorithm.</dd>
+
+<dt><tt>hcookie <i>hex</i></tt>/<dt>
+<dd>Specifies the host cookie used in the key agreement algorithm.</dd>
+
+<dt><tt>initsequence <i>index</i></tt>/<dt>
+<dd>Specifies the initial index used by the key list generator in the autokey protocol.</dd>
+
+<dt><tt>initkey <i>key</i></tt>/<dt>
+<dd>Specifies the initial key used by the key list generator in the autokey protocol.</dd>
+
+<dt><tt>timestamp <i>time</i></tt>/<dt>
+<dd>Specifies the NTP time (seconds) when the last autokey message was recieved.</dd>
+
+</dl>
+
+<dt><tt>pstatus <i>assocID</i></tt></dt>
+<dd>Sends a read status request to the server for the given association. The names and values of the peer variables returned will be printed. Note that the status word from the header is displayed preceding the variables, both in hexidecimal and in pidgeon English.</dd>
+
+<dt><tt>readlist [ <i>assocID</i> ]</tt></dt>
+<BR><tt>rl [ <i>assocID</i> ]</tt>
+<dd>Requests that the values of the variables in the internal variable list be returned by the server. If the association ID is omitted or is 0 the variables are assumed to be system variables. Otherwise they are treated as peer variables. If the internal variable list is empty a request is sent without data, which should induce the remote server to return a default display.</dd>
+
+<dt><tt>readvar <i>assocID</i> <i>variable_name</i> [ = <i>value</i> ] [ ...]</tt></dt>
+<BR><tt>rv <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i> ] [ ...]</tt>
+<dd>Requests that the values of the specified variables be returned by the server by sending a read variables request. If the association ID is omitted or is given as zero the variables are system variables, otherwise they are peer variables and the values returned will be those of the corresponding peer. Omitting the variable list will send a request with no data which should induce the server to return a default display.</dd>
+
+<dt><tt>writevar <i>assocID</i> <i>variable_name</i> [ = <i>value</i> [ ...]</tt></dt>
+<dd>Like the readvar request, except the specified variables are written instead of read.</dd>
+
+<dt><tt>writelist [ <i>assocID</i> ]</tt></dt>
+<dd>Like the readlist request, except the internal list variables are written instead of read.</dd>
+
+</dl>
+
+<h4>Bugs</h4>
-<DL>
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST1</TT></DD>
-
-<DL>
-<DD>
-Duplicate packet. A copy from somewhere.</DD>
-</DL>
-
-<DL>
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST2</TT></DD>
-
-<DL>
-<DD>
-Bogus packet. It is not a reply to a message previously sent. This can
-happen when the NTP daemon is restarted and before a peer notices.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST3</TT></DD>
-
-<DL>
-<DD>
-Unsynchronized. One or more timestamp fields are missing. This normally
-happens when the first packet from a peer is received.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST4</TT></DD>
-
-<DL>
-<DD>
-Either peer delay or peer dispersion is greater than one second. Ya gotta
-be kidding.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-The following <TT>TEST5</TT> through <TT>TEST10</TT> ennumerate errors
-in the packet header. The packet is discarded without inspecting its contents.</DD>
-
-<DL>
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST5</TT></DD>
-
-<DL>
-<DD>
-Cryptographic authentication fails. See the <A HREF="authopt.htm">Authentication
-Options</A> page.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST6</TT></DD>
-
-<DL>
-<DD>
-Peer is unsynchronized. Wind up its clock first.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST7</TT></DD>
-
-<DL>
-<DD>
-Peer stratum is greater than 15. The peer is probably unsynchronized.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST8</TT></DD>
-
-<DL>
-<DD>
-Either root delay or root dispersion is greater than one second. Too far
-from home.</DD>
-</DL>
-
-<DL>
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST9</TT></DD>
-
-<DL>
-<DD>
-Peer cryptographic authentication fails. Either the key identifier or key
-is wrong or somebody trashed our packet.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DD>
-<TT>TEST10</TT></DD>
-
-<DL>
-<DD>
-Access is denied. See the <A HREF="accopt.htm">Access Control Options</A>
-page.</DD>
-
-<DD>
- </DD>
-</DL>
-
-<DT>
-<TT>pstatus <I>assocID</I></TT></DT>
-
-<DD>
-Sends a read status request to the server for the given association. The
-names and values of the peer variables returned will be printed. Note that
-the status word from the header is displayed preceding the variables, both
-in hexidecimal and in pidgeon English.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>readlist [ <I>assocID</I> ]</TT></DT>
-
-<BR><TT>rl [ <I>assocID</I> ]</TT>
-<DD>
-Requests that the values of the variables in the internal variable list
-be returned by the server. If the association ID is omitted or is 0 the
-variables are assumed to be system variables. Otherwise they are treated
-as peer variables. If the internal variable list is empty a request is
-sent without data, which should induce the remote server to return a default
-display.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>readvar <I>assocID</I> <I>variable_name</I> [ = <I>value</I> ] [ ...
-]</TT></DT>
-
-<BR><TT>rv <I>assocID</I> [ <I>variable_name</I> [ = <I>value</I> ] [ ...
-]</TT>
-<DD>
-Requests that the values of the specified variables be returned by the
-server by sending a read variables request. If the association ID is omitted
-or is given as zero the variables are system variables, otherwise they
-are peer variables and the values returned will be those of the corresponding
-peer. Omitting the variable list will send a request with no data which
-should induce the server to return a default display.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>writevar <I>assocID</I> <I>variable_name</I> [ = <I>value</I> [ ...
-]</TT></DT>
-
-<DD>
-Like the readvar request, except the specified variables are written instead
-of read.</DD>
-
-<DD>
- </DD>
-
-<DT>
-<TT>writelist [ <I>assocID</I> ]</TT></DT>
-
-<DD>
-Like the readlist request, except the internal list variables are written
-instead of read.</DD>
-</DL>
-
-<H4>
-Bugs</H4>
The peers command is non-atomic and may occasionally result in spurious
error messages about invalid associations occurring and terminating the
-command. The timeout time is a fixed constant, which means you wait a long
-time for timeouts since it assumes sort of a worst case. The program should
-improve the timeout estimate as it sends queries to a particular host,
-but doesn't.
-<HR>
-<ADDRESS>
-David L. Mills (mills@udel.edu)</ADDRESS>
-
-</BODY>
-</HTML>
+command. The timeout time is a fixed constant, which means you wait a long time for timeouts since it assumes sort of a worst case. The program should improve the timeout estimate as it sends queries to a particular host, but doesn't.
+
+<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a
+href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a>
+</address></a></body></html>
However, it continues the tradition of retaining backwards compatibility
with older versions. The NTPv4 version has been under development for
quite a while and isn't finished yet. In fact, quite a number of NTPv4
-features have already been implemented in the current NTPv3. The primary
-purpose of this release is to verify the remaining new code compiles and
-runs in the various architectures, operating systems and hardware
-complement that can't be verified here. Of particular interest are
-Windows NT, VMS and various reference clock drivers. As always,
+features have already been retrofitted in the current NTPv3, although
+this version is not actively maintained by the NTPv4 developer's group.
+The primary purpose of this release is to verify the remaining new code
+compiles and runs in the various architectures, operating systems and
+hardware complement that can't be verified here. Of particular interest
+are Windows 2000, VMS and various reference clock drivers. As always,
corrections and bugfixes are warmly received, especially in the form of
context diffs.
<P><LI>The scheme for enabling the <TT>ppsclock</TT> line
discipline/streams module has changed. Formerly, it was enabled by
-setting f<TT>fudge flag3</TT> for the serial port connected to the PPS
+setting <TT>fudge flag3</TT> for the serial port connected to the PPS
signal. Now, there is an explicit command <TT>pps</TT> used to designate
the device name. See the <A HREF=clockopt.htm>Reference Clock
Options</A> page for details.</LI>
<H4>Caveats</H4>
This release has been compiled and tested on several systems, including
-SunOS 4.1.3, Solaris 2.5.1 and 2.7, Alpha 4.0, Ultrix 4.4, Linux,
-FreeBSD 3.4 and HP-UX 10.02. It has not been compiled for Windows NT or
-VMS. We are relying on the NTP volunteer brigade to do that. Known
-problems are summarized below:
+SunOS 4.1.3, Solaris 2.5.1-2.8, Alpha 4.0, Ultrix 4.4, Linux, FreeBSD
+3.4 and HP-UX 10.02. It has been compiled and tested on Windows NT, but
+not yet on any other Windows version or for VMS. We are relying on the
+NTP volunteer corps to do that. Known problems are summarized below:
<OL>
-<p><li>The latest NTPv4 <tt>ntpdc</tt> does not work with previous versions of <tt>ntpd</tt> and previous versions of <tt>ntpdc</tt> do not work with latest <tt>ntpd</tt>. This situation is regrettable and may be fixed in future; however, it is necessary in order for the autokey function to retrieve canonical names and certificates from directory services such as Secure DNS.
+<p><li>The latest NTPv4 <tt>ntpdc</tt> does not work with previous
+versions of <tt>ntpd</tt> and previous versions of <tt>ntpdc</tt> do not
+work with latest <tt>ntpd</tt>. This situation is regrettable and may be
+fixed in future; however, it is necessary in order for the autokey
+function to retrieve canonical names and certificates from directory
+services such as Secure DNS.
<P><LI>To work properly in all cases, the <TT>enable</TT> and
<TT>pps</TT> commands, if used, should appear before the <TT>server</TT>
and <TT>fudge</TT> commands in the configuration file.</LI>
-<P><LI>The precision time kernel modifications formerly in stock Solaris
-2.6 have bugs that were fixed in 2.7. A patch is available that fixes
-the 2.6 bugs. The 2.6 kernel discipline has been disabled by default.
-For testing, the kernel can be enabled using the <TT>enable kernel</TT>
-command either in the configuration file or via <TT>ntpdc</TT>.</LI>
+<P><LI>The latest release of NTP4 includes support for tne <a href=
+http://www.eecis.udel.edu/~mills/resource.htm><i>nanokernel</i></a>
+precision time kernel support, which is now in stock Linux and FreeBSD
+kernels. If a precision time source such as a GPS timing receiver or
+cesium clock is available, kernel timekeeping can be improved to the
+order less than one microsecond. The older precision time kernel for the
+Alpha continues to be supported. The precision time support in stock
+Solaris 2.6 has bugs that were fixed in 2.7. A patch is available that
+fixes the 2.6 bugs. The 2.6 kernel discipline has been disabled by
+default. For testing, the kernel can be enabled using the <TT>enable
+kernel</TT> command either in the configuration file or via
+<TT>ntpdc</TT>.</LI>
+
+<p><li>A new pulse-per-second (PPS) generic interface described in <a
+href=http://www.eecis.udel.edu/~mills/reports.htm>Mogul, J., D. Mills, J.
+Brittenson, J. Stone and U. Windl. Pulse-per-second API for Unix-like
+operating systems, version 1. Request for Comments RFC-2783, Internet
+Engineering Task Force, March 2000, 31 pp</a> is supported. Older
+interfaces and line disciplines continue to be supported, but may be
+withdrawen in future versions.
<P><LI>On Alpha 4.0 with reference clocks configured, debugging with the
<TT>-d</TT> options doesn't work.</LI>
-<P><LI>The autokey function uses NTP header extensions fields,
-which is documented in an Internet Draft and implemented in this
-release. At present the keys and related cryptographic data are stored
-in the form of files generated by the <a
-href=genkeys.htm>ntp_genkeys</a> program. It is expected that in future
-these values will be obtained automatically from the Secure DNS
-following deployment.</LI>
+<P><LI>The latest release of NTPv4 includes support for <i>autokey</i>
+public-key cryptography, which is the preferred scheme for
+authenticating servers to clients. It uses NTP header extensions fields
+documented in <a
+href=http://www.eecis.udel.edu/~mills/reports.htm>Mills, D.L. Public key
+cryptography for the Network Time Protocol. Electrical Engineering
+Report 00-5-1, University of Delaware, May 2000. 23 pp</a> and
+implemented in this release. However, the protocol is still evolving and
+some fields may not conform to that document. The design provides for
+orderly key refreshment and does not require public keys and related
+media to be copied from one machine to another. Specific information
+about autokey cryptography is contained in the <a
+href=authopt.htm>Authentication Options</a> page and links from
+thnere.</li>
<P><LI>The manycast function still needs some work. Ideally, the
existing I/O routines would be enhanced to include the capability to
projects / thirdparty / ntp.git / commitdiff
