HP OpenVMS Systems Documentation

The following commands make authenticated requests:

• addpeer peer-address key-ID [version] [prefer]
  Adds a configured peer association at the given address and operates in symmetric active mode. The existing association with the same peer can be deleted when this command is executed or can be converted to conform to the new configuration.
  The key-ID is the key identifier for requestkey , as described in Table 13-3. All outgoing packets to the remote server have an authentication field attached that is encrypted with this key.
  The value for version can be 1, 2, 3 or 4. The default is Version 4.
  The prefer keyword indicates a preferred peer that will be used for clock synchronization, if possible.
• addserver peer-address key-ID [version] [prefer]
  This command is the same as addpeer except that the operating mode is client.
• broadcast peer-address key-ID [version] [prefer]
  This command is the same as addpeer except that the operating mode is broadcast. In this case, a valid key identifier and key value are required. The peer-address parameter can be either the broadcast address of the local network or a multicast group address assigned to NTP.
• unconfig peer-address [...]
  Causes the configured bit to be removed from the specified remote peer. This command deletes the peer association. When appropriate, however, the association may persist in an unconfigured mode if the remote pee continues in this fashion.
• enable [flag] [...]
  disable [flag] [...]
  These commands operate in the same way as the enable and disable configuration commands. For details, see Section 13.3.2.
• fudge peer-address [time1] [time2] [stratum stratum] [refID]
  Provides a way to set time, stratum, and identification data for a reference clock. (The TCP/IP Services product supports only the local reference clock.)

Use the following syntax to enter the NTPDC foreign command:

NTPDC [-i] [-l] [-n] [-p] [-s] [-c command][host1,host2,...]

Table 13-6 describes the NTPDC options.

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 4. 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 (see Section 13.6.2).
• 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.7.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 assocID variable-name=value [,...]
  Like the readvar request except that the specified variables are written instead of read.

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.

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.7.5 Generating Random Keys with NTP_GENKEYS

The NTP_GENKEYS program allows you to generate random keys used by the NTP Version 3 and NTP Version 4 symmetric key authentication scheme. By default, the program generates the TCPIP$NTP.KEYS file containing 16 random symmetric keys. A timestamp is appended to the file name. Because the algorithms are seeded by the system clock, each run of the program produces a different file and file name.

The TCPIP$NTP.KEYS file contains 16 MD5 keys. Each key consists of 16 characters randomized over the ASCII 95-character printing subset. The file is read by the NTP server at the location specified by the keys configuration file command. An additional key consisting of an easily remembered password should be added manually for use with the NTPQ and NTPDC programs. The file must be distributed by secure means to other servers and clients that share the same security compartment. The key identifier for the MD5 program uses only identifiers 1 through 16. The key identifier for each association is specified as the key argument in the server or peer configuration file command.

13.8 Solving NTP Problems

Some common NTP problems include:

• System clock not synchronized.
  NTP cannot synchronize a clock that is off by more than 1000 seconds. To solve this problem, set the clock using NTPDATE, then restart NTP.
• NTPDATE fails to set the clock.
  This occurs if NTP is already running.
• More than one service is actively setting the system clock.
  NTP can run with other time services but must be explicitly instructed not to set the system clock. NTP can still provide synchronization to other clients even if it is not updating the system clock.
• NTP appears to be running without error, but the system clock is off by a one-, two-, three-, or four-hour interval.
  You might need to adjust the time zone differential. For more information, please consult the OpenVMS documentation set.

Once the configuration file has been created and edited, the next step is to verify correct operation and then fix any resulting problems.

13.8.1.1 Initial Startup

The best way to verify correct operation is by using the NTPQ and NTPDC programs, either on the server itself or from another machine elsewhere in the network. The NTPQ program implements the management functions specified in the NTP specification RFC 1305, Appendix A. The NTPDC program implements additional functions not provided in the standard. Both programs can be used to inspect the state variables defined in the specification and, in the case of NTPDC, additional ones of interest. In addition, the NTPDC program can be used to selectively reconfigure and enable or disable some functions while the server is running. Problems are apparent in the server's log file. The log file should show the startup banner, some brief initialization data, and the computed precision value.

Another common problem is incorrect DNS names. Check that each DNS name used in the configuration file exists and that the address responds to the ping command. When the server is first started it normally polls the servers listed in the configuration file at 64-second intervals. To allow a sufficient number of samples for the NTP algorithms to discriminate reliably between correctly operating servers and possible intruders, at least four valid messages from the majority of servers and peers listed in the configuration file are required before the server can set the local clock. However, if the difference between the client time and server time is greater than the panic threshold (which defaults to 1000 seconds), the server sends a message to the server log and shuts down without setting the clock. It is necessary to set the local clock to within the panic threshold first, either manually by wristwatch and the SET TIME command, or by using the NTPDATE command. The panic threshold can be changed by the tinker panic statement.