HP OpenVMS Systems Documentation

Section 12.3 discussed how to use the configuration file to configure NTP on your system. In addition to using a configuration file, you can make run-time changes to NTP with query commands by running the NTPDC utility. NTPDC displays time values in seconds.

Run-time requests are always authenticated requests. Authentication provides verification that the requester has permission to make such changes but also gives an extra degree of protection against transmission errors.

The reconfiguration facility works well with a server on the local host and between time-synchronized hosts on the same LAN. The facility works poorly for more distant hosts. Authenticated requests include a timestamp. The server compares the timestamp to its receive timestamp. If they differ by more than a small amount, the request is rejected. This is done for two reasons:

• It makes it more difficult for an intruder to overhear traffic on your LAN.
• It makes it more difficult for topologically remote hosts to request configuration changes to your server.

To run NTPDC, enter the following command:

$ RUN SYS$SYSTEM:TCPIP$NTPDC.EXE

At the NTPDC> prompt, enter the appropriate type of command from the following list:

• Interactive commands
• Control commands
• Run-time configuration request commands

Interactive commands consist of a command name followed by one or more keywords. The interactive commands are:

• help [ command_keyword ]
  Enter a question mark (?) to display a list of all the command keywords known to this version of NTPDC. Enter a question mark followed by a command keyword to display information about the function and use of the command.
• host hostname
  Set the host to which future queries will be sent. The hostname can be either a host name or a numeric address.
• hostnames [ yes | no ]
  If you specify yes , host names are displayed. If you specify no , numeric addresses are displayed instead. The default is yes unless you include the -n option on the command line, as described in Table 12-4.
• keyid key-ID
  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.
• quit
  Exits NTPDC.
• passwd
  This command prompts you to type in a password (not echoed) that 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.
• timeout milliseconds
  Specify a timeout period for responses to server queries. The default is about 8000 milliseconds (8 seconds). Because NTPDC retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.

Control message commands request information about the server. These are read-only commands in that they make no modification of the server configuration state.

The NTPDC control message commands are:

• listpeers
  Displays a brief list of the peers for which the server is maintaining state. These include all configured peer associations as well as those peers whose stratum is such that they are considered by the server to be possible future synchonization candidates.
• peers
  Obtains a list of peers for which the server is maintaining state, along with a summary of that state. The summary information includes:
  • The address of the remote peer
  • The local interface address (0.0.0.0 if a local address has not been determined)
  • The stratum of the remote peer (a stratum of 16 indicates the remote peer is unsynchronized)
  • The polling interval (in seconds)
  • The reachability register (in octal)
  • The current estimated delay, offset, and dispersion of the peer (in seconds)
  
  In addition, the character in the left margin indicates the mode this peer entry is operating in, as follows:

  Plus sign (+) denotes symmetric active.
  Minus sign (-) indicates symmetric passive.
  Equals sign (=) means the remote server is being polled in client mode.
  Up arrow (^) indicates that the server is broadcasting to this address.
  Tilde (~) denotes that the remote peer is sending broadcasts.
  Asterisk (*) marks the peer to which the server is currently synchronizing.

  
  The contents of the host field may be one of four forms. It may be:
  • Host name
  • IP address
  • Reference clock implementation name with its parameter
  • REFCLK (implementation number parameter) .
  
  If you specify hostnames no , only IP addresses will be displayed.
• dmpeers
  Displays a slightly different peer summary list, identical to the output of the peers command, except for the character in the leftmost column. Characters only appear beside peers that were included in the final stage of the clock selection algorithm.

  Dot (.) indicates that this peer was rejected in the falseticker detection.
  Plus sign (+) indicates that the peer was accepted.
  Asterisk (*) denotes the peer to which the server is currently synchronizing.

• showpeer peer_address [...]
  Shows a detailed display of the current peer variables for one or more peers.
• pstats peer_address [...]
  Shows per-peer statistics counters associated with the specified peers.
• loopinfo [ oneline multiline ]
  Displays the values of selected loop-filter variables. The loop filter is the part of NTP that adjusts the local system clock. These options include:
  • offset --- the last offset given to the loop filter by the packet processing code.
  • frequency --- the frequency error of the local clock (in parts per million)
  • time_const --- controls the stiffness of the phase-lock loop and thus the speed at which it can adapt to oscillator drift.
  • watchdog timer value --- the number of seconds that have elapsed since the last sample offset was given to the loop filter.
  
  The oneline and multiline options specify the format in which this information is to be displayed; multiline is the default.
• sysinfo
  Displays a variety of system state variables, such as the state related to the local server.
  The system flags show various system flags, some of which can be set and cleared by the enable and disable configuration commands, respectively. These are the auth , bclient , monitor , pll , pps and stats flags.
  The stability is the residual frequency error remaining after the system frequency correction is applied. It is intended for maintenance and debugging.
  The broadcastdelay shows the default broadcast delay, as set by the broadcastdelay configuration command.
  The authdelay shows the default authentication delay, as set by the authdelay configuration command.
• sysstats
  Displays statistics counters maintained in the protocol module.
• memstats
  Displays statistics counters related to memory allocation code.
• iostats
  Displays statistics counters maintained in the input/output module.
• timerstats
  Displays statistics counters maintained in the timer/event queue support code.
• reslist
  Displays the server's restriction list. This list is displayed in the order in which the restrictions are applied.

• monlist [ version ]
  Displays traffic counts collected. This is maintained by the monitor facility. Normally, you should not need to specify the version number.

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 may be deleted when this command is executed or may be converted to conform to the new configuration.
  The key-ID is the key identifier for requestkey , as described in Table 12-2. All outgoing packets to the remote server will have an authentication field attached that is encrypted with this key.
  The value for version can be 1, 2, or 3. The default is Version 3.
  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 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 deletes the peer association. When appropriate, however, the association may persist in an unconfigured mode if the remote peer is willing to continue in this fashion.
• enable [flag] [...]
  disable [flag] [...]
  These commands operate in the same way as the enable and disable configuration commands. See Section 12.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.)

You can also run NTPDC by defining a foreign command as follows:

$ NTPDC:==$SYS$SYSTEM:TCPIP$NTPDC.EXE

Use the following syntax when entering commands:

NTPDC [option...]

Table 12-5 describes the NTPDC options.

The NTPQ program allows you to query the NTP server about its current state and 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, as described in Table 12-2.

The NTPQ program uses NTP mode 6 packets to communicate with the NTP server; therefore, it is used to 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:

$ RUN SYS$SYSTEM:TCPIP$NTPQ.EXE

At the NTPQ> prompt, enter commands using 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 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 more than one variable is to be added, the list should be separated by commas and should not contain blank spaces. The rmvars command can be used to remove individual variables from the list, while the clearlist 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 level of NTPQ debugging. The default is debug no .
• help
  Displays the list of NTPQ interactive commands. This is the same as question mark (?).
• host [host-name]
  Sets the host to which future queries will be sent; host-name may 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 (see Section 10.7.2).
• keytype md5 | des
  Sets the authentication key to either MD5 or DES. Only MD5 is supported in this implementation.
• ntpversion 1 | 2 | 3
  Sets the NTP version number that NTPQ claims in packets. Default is 3. Mode 6 control messages (and modes, for that matter) did not exist in NTP version 1.

• passwd
  Prompts you to enter a password (not echoed) that is used to authenticate configuration requests. The password must correspond to the key value configured for use by the NTP server for this purpose if such requests are to be successful (see Section 12.7.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 will be 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 12.8.4. Most 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 numbering 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 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 form index\\ may 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 which retain state for out-of-spec client associations. Such associations are normally 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:

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

  
  Since the peers command depends on the ability to parse the values in the responses it gets, it might fail to work with servers that poorly control the data formats.
  The contents of the host field may in be 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 will be displayed.
• pstatus assocID
  Sends a read status request to the server for the given association. The names and values of the peer variables returned will be 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 given as 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.

You can also run NTPQ by defining a foreign command as follows:

NTPQ:==$SYS$SYSTEM:TCPIP$NTPQ.EXE

Use the following syntax when entering the NTPQ foreign command:

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

Table 12-6 describes the NTPQ options.