NTP is started automatically if you selected NTP while running the configuration procedure after installation.

To stop NTP, enter the following command:

$ @SYS$STARTUP:TCPIP$NTP_SHUTDOWN.COM

To restart NTP, enter the following command:

$ @SYS$STARTUP:TCPIP$NTP_STARTUP.COM

10.4 Operating with Time Zone Offsets

The operating system's installation procedure provides a command procedure that defines a time zone differential (offset) logical name in the system logical name table (LNM$SYSTEM_TABLE). The procedure is SYS$COMMON:[SYSMGR]UTC$CONFIGURE_TDF.COM. The logical name is SYS$TIMEZONE_DIFFERENTIAL.

To define a time zone offset, follow these steps:

1. Run the command procedure SYS$COMMON:[SYSMGR]UTC$CONFIGURE_TDF.
2. Select an option to set the time differential factor.
   The procedure prompts you for the time differential factor (the difference between your system time and Coordinated Universal Time (UTC)). Specify the difference in hh:mm format.
   North and South America have negative offsets from UTC. Europe, Africa, Asia, and Australia all have positive offsets. Enter the time differential factor.
3. The procedure asks whether or not you want to modify the local system time.
   Respond yes or no.
   The procedure defines the system logical name SYS$TIMEZONE_DIFFERENTIAL to be the system time differential factor (or time zone offset). For example, during the summer months in Boston, the procedure defines SYS$TIMEZONE_DIFFERENTIAL as -14400 seconds.
4. If NTP is enabled, follow these additional steps:
   Stop NTP. Enter:

   $ @SYS$STARTUP:TCPIP$NTP_SHUTDOWN.COM

   
   Restart NTP. Enter:

   $ @SYS$STARTUP:TCPIP$NTP_STARTUP.COM

NTP maintains a record of system clock updates in the file SYS$SPECIFIC:[TCPIP$NTP]TCPIP$NTP.LOG. NTP reopens this log file daily, each time creating a new version of the file (older versions are not automatically purged). Events logged to this file may include the following messages:

• Synchronization status that indicates synchronization occurred, was lost, was reestablished, stratum changes, and so on.
• System time adjustments
• Time adjustment status
• Packet transmission status

Table 10-1 describes the messages you will most frequently find in an NTP log file.

Table 10-1 NTP Log File Messages

Message	Description
Synchronized to IP_address	Announces that a peer candidate has passed validity and accuracy tests (as performed by the clock selection algorithms) and has been selected as the new synchronization source. For example: synchronized to 16.20.208.100, stratum=2
Time reset time	Indicates that NTP has set the local clock by slewing the local time to match the synchronization source. This happens because the local host is no longer in synchronization. For example: time reset (slew) -0.218843 sec
Synchronization lost	This usually occurs after a time reset. All peer filter registers are cleared, for example, for that particular peer, all state variables are reset along with the polling interval, and the clock selection procedure is once again performed.
Previous time adjustment incomplete	Indicates that the last clock adjustment did not finish in one attempt. The residual is added to the next adjustment.
Couldn't resolve hostname, giving up on it	Indicates the host name could not be resolved. This peer will not be considered for the candidate list of peers. For example: couldn't resolve 'fred', giving up on it
Sendto IP_address: msg	Indicates that a problem occurred while sending a packet to its destination. Most common msg logged is "connection refused." For example: sendto(16.20.208.100): connection refused
Connection reestablished to IP_addrress	Indicates that errors occurred when sending packets, but now packets are being successfully sent. For example: connection reestablished to 16.20.208.100

10.5.0.1 Sample NTP Log File

The following sample shows an NTP log file:

16 Apr 16:36:30 ntpd version = 3-5.91 16 Apr 16:36:31 tickadj = 97, tick = 976, tvu_maxslew = 99231, est. hz = 1024 16 Apr 16:36:31 precision = 976 usec 16 Apr 16:36:33 read drift of 0 from TCPIP$NTP.DRIFT 16 Apr 16:43:00 synchronized to 16.20.208.100, stratum=2 16 Apr 16:43:00 time reset (slew) -62.810275 sec 16 Apr 16:43:00 synchronization lost 16 Apr 16:44:58 Previous time adjustment incomplete; residual -0.005758 sec 16 Apr 16:48:21 synchronized to 16.20.208.100, stratum=2 16 Apr 16:52:28 Previous time adjustment incomplete; residual -0.005270 sec 16 Apr 16:53:26 Previous time adjustment incomplete; residual -0.085888 sec 16 Apr 17:11:40 synchronized to 16.20.208.23, stratum=3 16 Apr 17:13:49 synchronized to 16.20.208.100, stratum=2 16 Apr 17:14:53 time reset (slew) -0.577109 sec 16 Apr 17:14:53 synchronization lost 16 Apr 17:21:38 synchronized to 16.20.208.23, stratum=3 16 Apr 17:26:54 synchronized to 16.20.208.100, stratum=2 16 Apr 17:46:23 synchronized to 16.20.208.97, stratum=3 16 Apr 17:47:28 Previous time adjustment incomplete; residual -0.000020 sec 16 Apr 17:49:32 Previous time adjustment incomplete; residual 0.093696 sec 16 Apr 17:49:36 Previous time adjustment incomplete; residual 0.003318 sec 16 Apr 17:52:08 Previous time adjustment incomplete; residual -0.049460 sec 16 Apr 17:52:24 Previous time adjustment incomplete; residual 0.003416 sec 16 Apr 17:53:28 Previous time adjustment incomplete; residual 0.000088 sec 16 Apr 18:06:10 time reset (slew) -0.218843 sec 16 Apr 18:06:11 synchronization lost 16 Apr 18:17:39 synchronized to 16.20.208.97, stratum=3 16 Apr 18:17:43 synchronized to 16.20.208.100, stratum=2 16 Apr 18:21:47 synchronized to 16.20.208.97, stratum=3 16 Apr 18:23:41 synchronized to 16.20.208.100, stratum=2

10.6 Authentication Support

Authentication support is implemented using the MD5 algorithm to compute a message digest. The servers involved in an association must agree on the key and key identifier used to authenticate their messages.

Keys and related information are specified in a key file. There are three classes of keys: one for ordinary NTP associations, another for the NTPQ utility program and the third for the NTPDC utility program.

10.6.1 Authentication Commands

Table 10-2 describes additional configuration statements and options used to support authentication.

Table 10-2 Authentication Commands

Command	Description
keys keyfile	Specifies the file name containing the encryption keys and key identifiers used by NTP, NTPQ, and NTPDC when operating in authenticated mode.
trustedkey key [...]	Specifies the encryption key identifiers that are trusted for the purposes of authenticating peers suitable for synchronization, as well as keys used by the NTPQ and NTPDC 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 key arguments are 32-bit unsigned integers with values of 1-15. Note that NTP key 0 is used to indicate an invalid key and/or key identifier, so it should not be used for any other purpose.
requestkey key	Specifies the key identifier to use with the NTPDC program, which uses a proprietary protocol specific to this implementation of NTP. This program is useful to diagnose and repair problems that affect NTP operation. The key argument to this command is a 32-bit key identifier for a previously defined trusted key. If no requestkey command is included in the configuration file, or if the keys don't match, any request to change a server variable will be denied.
controlkey key	Specifies the key identifier to use with the NTPQ program, which uses the standard protocol defined in RFC-1305. This program is useful to diagnose and repair problems that affect the operation of NTP. The key argument to this command is a 32-bit key identifier for a trusted key in the key cache. If no controlkey command is included in the configuration file, or if the keys don't match, any request to change a server variable will be denied.

10.6.2 Authentication Key File Format

NTP reads its key from a file specified using the keys statement in the configuration file. While the key ID number 0 is fixed (56 zero bits), one or more of the keys numbered 1 through 15 may be arbitrarily set in the keys file.

Key entries use a fixed format as follows:

key_ID key_type key_value

The fields are:

• key_ID, which is an arbitrary, unsigned 32-bit number, written in decimal. The range of possible values is 1-15. Key IDs are specified by the requestkey and controlkey statements in the configuration file.
• key_type, which identifies the type of key_value. Only one key format, ``M'', is currently supported. This indicates that the MD5 authentication scheme is being used.
• key_value, a 1-to-8 character ASCII string. Note that both the keys and key_type must be identical between a set of peers sharing the same key number. The following characters are not allowed: space, pound sign (#), '\t', '\n', and '\0'.

Because this file contains authorization data, you are strongly urged to limit read permission for this file. In particular, you should remove read permission for other users.

Below is a sample keys file:

# # 4 M DonTTelL 6 M hElloWrl 22 M ImASecrt

10.7 NTP Utilities

NTP provides several utility programs that help you manage and make changes to the NTP server. These utilities include:

• TCPIP$NTPDATE, the date and time utility that sets the local date and time by polling the specified server. Run NTPDATE manually or from the host startup script to set the clock at boot time before NTP starts.
  NTPDATE will not set the date if NTP is already running on the same host.
• TCPIP$NTPTRACE, the trace utility that follows the chain of NTP servers back to their master time source.
• TCPIP$NTPDC, the special query program that provides extensive state and statistics information and that can be used to set configuration options at run time. Run this program in interactive mode or with command line arguments.
• TCPIP$NTPQ, the standard query program that queries NTP servers about their current state and requests changes to that state.

The following sections provide more information about these utilities.

10.7.1 Setting the Date and Time with NTPDATE

The NTPDATE program sets the local date and time by polling a specified server or servers to determine the correct time. A number of samples are obtained from each of the servers specified, and a subset of the NTP clock filter and selection algorithms are applied to select the best of these. Note that the accuracy and reliability of NTPDATE depends on the number of servers it polls, the number of polls it makes each time it runs, and the interval length between runs.

Run NTPDATE manually to set the host clock or from the host startup file to set the clock at boot time. It is useful in some cases to set the clock initially before starting NTP. NTPDATE makes time adjustments (called stepping the time) by calling the OpenVMS routine SYS$SETIME.

Table 10-3 describes some of the NTPDATE command options. To use these options, define a foreign command as follows:

ntpdate:==$SYS$SYSTEM:TCPIP$NTPDATE.EXE

Enter commands using the following syntax:

$ ntpdate [option...] host [host...]

For example:

$ ntpdate birdy owl fred

will set the clock based on the time provided from one of the specified hosts (birdy, owl, or fred). The host selected is determined to be the most accurate and reliable source.

Table 10-3 NTPDATE Options

Option	Description
-d	Changes the time and prints information useful for debugging.
-o version	Specifies the NTP version (1 or 2) for outgoing packets (for compatibility with older versions of NTP). If you do not specify a version number, version 3 is the default.
-p n	Specifies the number (1-8) of samples NTPDATE acquires from each server. The default is 4.
-q	Specifies a query only; does not set the clock.

For additional information on NTPDATE options, see the UNIX manual reference page ntpdate(8).

10.7.2 Tracing a Time Source with NTPTRACE

Use the NTPTRACE utility to determine the source from which an NTP server obtains its time. NTPTRACE follows the chain of time servers back to the master time source.

To run NTPTRACE, define a foreign command as follows:

$ ntptrace:==$SYS$SYSTEM:TCPIP$NTPTRACE.EXE

Use the following syntax when entering commands:

ntptrace [option...]

The following example shows output from an NTPTRACE. In this example, the chain of servers from the local host to the stratum-1 server FRED, which is synchronizing to a GPS reference clock.

$ NTPTRACE LOCALHOST: stratum 3, offset -0.000000, synch distance1.50948 parrot.birds.com: stratum 2, offset -0.126774, synch distance 0.00909 fred.birds.com: stratum 1, offset -0.129567, synch distance 0.00168, refid 'GPS'

All times are in seconds. The output fields on each line are as follows:

• Host name
• Host's stratum
• Time offset between the host and the local host (not always 0 (zero) for LOCALHOST).
• Synchronization distance
• Reference clock ID (only for stratum-1 servers)

Table 10-4 describes the NTPTRACE command options.

Table 10-4 NTPTRACE Options

Option	Description
-d	Turns on some debugging output.
-n	Turns off the printing of host names; instead, host IP addresses are given. This may be necessary if a name server is down.
-r retries	Sets the number of retransmission attempts for each host. The default is 5.
-t timeout	Sets the retransmission timeout (in seconds). The default is 2.
-v	Prints verbose information about the NTP servers.

10.7.3 Making Run-time Requests with NTPDC

Section 10.2 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 and 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 commands using the following syntax:

command [options...]

Type HELP at the NTPDC> prompt for a complete list of interactive commands.

The following commands make authenticated requests:

• addpeer peer_address keyid [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 as appropriate.
  The keyid is a non-zero number. All outgoing packets to the remote server wil have an authentication field attached that is encrypted with this key.
  The version number can be 1, 2, or 3 and defaults to 3.
  The prefer keyword indicates a preferred peer that will be used for clock synchronization, if possible.
• addserver peer_address keyid [version] [prefer]
  Same as addpeer, except that the operating mode is client.
• broadcast peer_address keyid [version] [prefer]
  Same as addpeer, except that the operating mode is broadcast. In this case, a valid key identifier and key 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 10.2.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 only supports 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 10-5 describes the NTPDC command options. For more information, see the UNIX manual reference page xntpdc(8).

Table 10-5 NTPDC Options

Option	Description
-c command	The command 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.
-i	Forces NTPDC to operate in interactive mode.
-l	Obtains a list of peers that are known to the server(s).
-n	Outputs all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
-o version	By default, NTPDC identifies itself as an NTP version 3 implementation in its outgoing packets, however, version 2 implementations of NTP do not respond to version 3 queries. Use this option to force the program to behave as a version 2 implementation instead.
-p	Prints a list of the peers known to the server as well as a summary of their state.
-s	Prints a list of the peers known to the server as well as a summary of their state, but in a slightly different format than the -p option.