The NTPQ program allows you to query the NTP server about its current state and to request changes to that state. NTPQ can also obtain and display a list of peers in a common format by sending multiple queries to the server.

The NTPQ program authenticates requests based on the key entry in the keys file that is configured using the controlkey command (described in Table 13-3).

The NTPQ program uses NTP mode 6 packets to communicate with the NTP server; therefore, NTPQ can query any compatible server on the network. Because NTP is a UDP protocol, this communication is somewhat unreliable over long distances (in terms of network topology). The NTPQ program makes one attempt to restransmit requests and times out requests if the remote host does not respond within the expected amount of time. NTPQ displays time values in milliseconds.

To run the NTPQ program, enter the following command:

$ NTPQ NTPQ>

At the NTPQ> prompt, enter commands in the following syntax:

command [options...]

The following commands allow you to query and set NTP server state information:

• ? [command-keyword]
  A question mark (?) by itself prints a list of all the command keywords known to this version of NTPQ. A question mark followed by a command keyword prints function and usage information about the command.
• addvars variable-name[=value] [,...]
• rmvars variable-name [,...]
• clearvars
  The data carried by NTP mode 6 messages consists of a list of items in the following form:

  variable-name=value

  
  In requests to the server to read variables, the =value portion is ignored and can be omitted. The NTPQ program maintains an internal list in which data to be included in control messages can be assembled and sent using the readlist and writelist commands. The addvars command allows variables and their optional values to be added to the list. If you want to add more than one variable, separate the list items by commas and do not include blank spaces. The rmvars command removes individual variables from the list, while the clearvars command removes all variables from the list.

• authenticate yes | no
  By default, NTPQ does not authenticate requests unless they are write requests. The authenticate yes command causes NTPQ to send authentication with all requests it makes. Authenticated requests cause some servers to handle requests slightly differently. To prevent any mishap, do a peer display before turning on authentication.
• cooked
  Reformats variables that are recognized by the server. Variables that NTPQ does not recognize are marked with a trailing question mark (?).
• debug more | less | no
  Adjusts the level of NTPQ debugging. The default is debug no .
• help
  Displays the list of NTPQ interactive commands. This is the same as entering a question mark (?).
• host [hostname]
  Sets the host to which future queries will be sent; host-name can be either a host name or an Internet address. If host-name is not specified, the current host is used.
• hostnames yes | no
  If yes is specified, displays host names in information displays. If no is specified, displays Internet addresses instead. The default is hostnames yes . The default can be modified using the command line option -n .
• key-ID n
  Specifies the key ID number to be used to authenticate configuration requests. This must correspond to a key ID number the server has been configured to use for this purpose.
• keytype md5 | des
  Sets the authentication key to either MD5 or DES. Only MD5 is supported in this implementation.
• ntpversion 1 | 2 | 3 | 4
  Sets the NTP version number that NTPQ claims in packets. The default is Version 2 to maintain compatibility with older versions. Mode 6 control messages (as well as modes) did not exist in NTP Version 1.

• passwd
  Prompts you to enter a password (not echoed) to be used to authenticate configuration requests. The password must correspond to the key value configured for use by the NTP server for this purpose.
• quit
  Exits NTPQ.
• raw
  Displays all output from query commands as received from the remote server. The only data formatting performed is to translate non-ASCII data into a printable form.
• timeout milliseconds
  Specifies a timeout period for responses to server queries. The default is about 5000 milliseconds. Since NTPQ retries each query once after a timeout, the total waiting time for a timeout is twice the timeout value.

Each peer known to an NTP server has a 16-bit integer association identifier assigned to it. NTP control messages that carry peer variables must identify the peer that the values correspond to by including the peer's association ID. An association ID of zero indicates the variables are system variables whose names are drawn from a separate name space.

Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to be displayed in a format that you control using the commands listed in Section 13.8.4. Most control message commands send a single message and expect a single response. The exceptions are the peers command, which sends a preprogrammed series of messages to obtain the data it needs, and the mreadlist and mreadvar commands, which are repeated for each specified association.

• associations
  Displays a list of association identifiers and peer status for recognized peers of the server being queried. The list is printed in columns. The first of these is an index that numbers the associations from 1 for internal use; the second is the actual association identifier returned by the server; and the third is the status word for the peer. This list is followed by a number of columns containing data decoded from the status word. The data returned by the associations command is cached internally in NTPQ. The index is then used when dealing with servers that use association identifiers. For any subsequent commands that require an association identifier as an argument, the index can be used as an alternative.
• lassociations
  Obtains and displays a list of association identifiers and peer status for all associations for which the server is maintaining state. This command differs from the associations command only for servers that retain state for out-of-spec client associations. Normally such associations are omitted from the display when the associations command is used but are included in the output of the lassociations command.

• lopeers
  Obtains and displays a list of all peers and clients having the destination address.
• lpassociations
  Displays data for all associations, including unrecognized client associations, from the internally cached list of associations.
• lpeers
  Similar to peers except that a summary of all associations for which the server is maintaining state is displayed. This command can produce a much longer list of peers.
• mreadlist assocID assocID
  Similar to the readlist command except that 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 associations command.
• mreadvar assocID assocID[variable-name[=value] [,...] ]
  Similar to the readvar command except that 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 associations command.
• opeers
  An old form of the peers command, with the reference ID replaced by the local interface address.
• passociations
  Displays association data concerning recognized peers from the internally cached list of associations. This command performs identically to the associations command except that it displays the internally stored data rather than make a new query.
• peers
  Displays a list of recognized 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 the reference ID is unknown); the stratum of the remote peer; the polling interval (in seconds); the reachability register (in octal); and the current estimated delay, offset, and dispersion of the peer (in milliseconds).
  The character in the left margin indicates the fate of this peer in the clock selection process. The codes are as follows:

  Table 13-7 Peer State Symbols

  Symbol	Indicates
  Space	The peer was discarded, because of high stratum or failed sanity checks.
  Lowercase x	The peer was designated a "falseticker" by the intersection algorithm.
  Dot (.)	The peer was culled from the end of the candidate list.
  Hyphen (-)	The peer was discarded by the clustering algorithm.
  Plus sign (+)	The peer was included in the final selection set.
  Pound sign (#)	The peer was selected for synchronization, but the distance exceeds the maximum.
  Asterisk (*)	The peer was selected for synchronization.

  
  Because the peers command depends on the ability to parse the values in the responses it gets, it might fail to work with servers that control the data formats poorly.
  The contents of the host field can be in one of four forms: a host name, an IP address, a reference clock implementation name with its parameter, or REFCLK (implementation number parameter). If you specified hostnames no , the IP addresses are displayed.

• pstatus assocID
  Sends a read status request to the server for the given association. The names and values of the peer variables returned are printed. The status word from the header is displayed preceding the variables, both in hexadecimal and in English.
• readlist [assocID]
  Requests that the server return the values of the variables in the internal variable list. If the association ID is omitted or is zero, 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; the remote server should return a default display.
• readvar [assocID] [variable-name[=value] [,...]]
  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 zero, the variables are system variables; otherwise, they are peer variables, and the values returned are those of the corresponding peer. If the variable list is empty, a request is sent without data; the remote server should return a default display.
• showvars
  Displays the variables on the variable list.
• version
  Displays the NTPQ version number.
• writelist [assocID]
  Like the readlist request except that the internal list variables are written instead of read.
• writevar assocIDvariable-name=value [,...]
  Like the readvar request except that the specified variables are written instead of read. At this time, no variables can be modified with the writevar command.

Use the following syntax to enter the NTPQ foreign command:

NTPQ [-i] [-n] [-p] [-c command] [host1,host2,...]

Table 13-8 describes the NTPQ options.

Table 13-8 NTPQ Options

Option	Description
-c command	Adds the specified interactive command to the list of commands to be executed on the specified host. You can enter multiple -c options on the command line.
-i	Forces NTPQ to operate in interactive mode. This is the default mode of operation.
-n	Displays host addresses numeric format rather than converting them to host names.
-p	Displays a list of the peers known to the server as well as a summary of their state.

The -c and -p options send the query to the specified host immediately. If you omit the host names, the default is the local host. To enter interactive mode, specify the -i or -n option.

13.9 Generating Public and Private Keys with ntp_keygen

This program generates cryptographic data files used by the NTPv4 authentication and identification schemes. It generates MD5 key files used in symmetric key cryptography. In addition, if the OpenSSL software library has been installed, it generates keys, certificate, and identity files used in public key cryptography. These files are used for cookie encryption, digital signature and challenge/response identification algorithms compatible with the Internet standard security infrastructure.

By default, files are not encrypted by ntp_keygen . The -p password option specifies the write password and -q password option the read password for previously encrypted files. If an encrypted file is read successfully and no write password is specified, the read password is used as the write password by default.

The NTP Server configuration command crypto pw password specifies the read password for previously encrypted files. The server exits if the password is missing or incorrect. For convenience, if a file has been previously encrypted, the default read password is the name of the host running the program. If the previous write password is specified as the host name, these files can be read by that host with no explicit password.

All files are in PEM-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities. File names begin with the prefix tcpip$ntpkey_ and end with the postfix _hostname.filestamp, where hostname is usually the string returned by the gethostname() routine, and filestamp is the NTP seconds when the file was generated, in decimal digits. This both guarantees uniqueness and simplifies maintenance procedures, because all files can be quickly removed by the delete tcpip$ntpkey* command or all files generated at a specific time can be removed by the delete *.filestamp command. To further reduce the risk of misconfiguration, the first two lines of a file contain the file name and generation date and time as comments.

All files are installed by default in the keys directory sys$specific:[tcpip$ntp] . The actual location of the keys directory and each file can be overridden by configuration commands, but this is not recommended. Normally, the files for each host are generated by that host and used only by that host, although exceptions exist as noted later on this page. Files are given read (R), write (W), and delete (D) access for system (S) and owner (O).

The recommended practice is to keep the file name extensions when installing a file and to install a symbolic link from the generic names specified elsewhere on this page to the generated files. This allows new file generations to be activated simply by changing the link. If a link is present, NTP Server follows it to the file name to extract the filestamp. If a link is not present, NTP Server extracts the filestamp from the file itself. This allows clients to verify that the file and generation times are always current. The ntp_keygen program uses the same extension for all files generated at one time, so each generation is distinct and can be readily recognized in monitoring data.

13.9.1 Synopsis

ntp_keygen [ -deGgHIMPT ] [ -c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [ -i name ] [ -l file] [ -p password ] [ -q password] [ -m modulus] [-r hostname] [ -S [ RSA | DSA ] ] [ -s name ] [ -v nkeys ] [ -V nkeys ]

13.9.2 Running ntp_keygen

When run for the first time, or if all tcpip$ntpkey files have been removed, the program generates a RSA host key file and matching RSA-MD5 certificate file, which is all that is necessary in many cases. The program also generates symbolic links from the generic names to the respective files. If run again, the program uses the same host key file, but generates a new certificate file and link.

The host key is used to encrypt the cookie when required and so must be RSA type. By default, the host key is also the sign key used to encrypt signatures. When necessary, a different sign key can be specified and this can be either RSA or DSA type. By default, the message digest type is MD5, but any combination of sign key type and message digest type supported by the OpenSSL library can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 and RIPE160 message digest algorithms. However, the scheme specified in the certificate must be compatible with the sign key. Certificates using any digest algorithm are compatible with RSA sign keys; however, only SHA and SHA1 certificates are compatible with DSA sign keys.

Private/public key files and certificates are compatible with other OpenSSL applications and very likely other libraries as well. Certificates or certificate requests derived from them should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identification parameter files, although encoded as the other files, are probably not compatible with anything other than Autokey.

Installing the keys with the default protections might not work in NFS-mounted shared file systems, as NFS clients may not be able to write to the shared keys directory. In this case, NFS clients can specify the files in another directory using the keysdir command. There is no need for one client to read the keys and certificates of other clients or servers, as these data are obtained automatically by the Autokey protocol.

Ordinarily, cryptographic files are generated by the host that uses them, but it is possible for a trusted agent (TA) to generate these files for other hosts; however, in such cases files should always be encrypted. The subject name and trusted name default to the hostname of the host generating the files, but can be changed b y command line options. It is convenient to designate the owner name and trusted name as the subject and issuer fields, respectively, of the certificate. The owner name is also used for the host and sign key files, while the trusted name is used for the identity files.

13.9.3 Random Seed File

All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the library routines. The OpenSSL library uses a designated random seed file for this purpose. The file must be available when starting NTP and the ntp_keygen program. If a site supports OpenSSL, it is very likely that means to do this are already available.

It is important to understand that entropy must be evolved for each generation, for otherwise the random number sequence would be predictable. Various means dependent on external events, such as keystroke intervals, can be used to do this and some systems have built-in entropy sources. Suitable means are described in the OpenSSL software documentation, but are outside the scope of this discussion.

The entropy seed used by the OpenSSL library is contained in a file, usually called .rnd , which must be available when starting NTP or the ntp_keygen program. The NTP Server will first look for the file using the path specified by the randfile subcommand of the crypto configuration command. If not specified in this way, or when starting the ntp_keygen program, the OpenSSL library will look for the file in the user home directory. If not found there, the OpenSSL library will look in the location specified by the keysdir configuration command that defaults to sys$specific:[tcpip$ntp] . If the file is not available or cannot be written, NTP writes a message to the NTP log file and then exits.