HP OpenVMS Systems Documentation

The Network Time Protocol (NTP) synchronizes time and coordinates time distribution throughout a TCP/IP network. NTP provides accurate and dependable timekeeping for hosts on TCP/IP networks. TCP/IP Services NTP software is an implementation of the NTP Version 3 specification and maintains compatibility with NTP versions 1 and 2.

NTP provides synchronization traceable to clocks of high absolute accuracy and avoids synchronization to clocks keeping incorrect time.

Time synchronization is important in client/server computing. For example, systems that share common databases require coordinated transaction processing and timestamping of instrumental data.

This chapter reviews key concepts and describes:

• How to start up and shut down NTP ( Section 12.2)
• How to configure the NTP host ( Section 12.3)
• How to configure the host as a backup time server ( Section 12.4)
• How to adjust time zone offsets ( Section 12.5)
• NTP event logging ( Section 12.6)
• How to configure NTP authentication ( Section 12.7)
• How to use NTP utilities ( Section 12.8)
• How to solve NTP problems ( Section 12.9)

Synchronized timekeeping means that hosts with accurate system timestamps send time quotes to each other. Hosts running NTP may be either time servers or clients although they are often both servers and clients.

NTP does not attempt to synchronize clocks to each other. Rather, each server attempts to synchronize to Universal Coordinated Time (UTC) using the best available source and best available transmission paths to that source. NTP expects that the time being distributed from the root of the synchronization subnet will be derived from some external source of UTC (for example, a radio clock).

If your network is isolated and you cannot access other NTP servers on the internet, you can designate one of your nodes as the reference clock to which all other hosts will synchronize.

12.1.1 Time Distributed Through a Hierarchy of Servers

In the NTP environment, time is distributed through a hierarchy of NTP time servers. Each server adopts a stratum that indicates how far away it is operating from an external source of UTC. NTP times are an offset of UTC. Stratum 1 servers have access to an external time source, usually a radio clock. A stratum 2 server is one that is currently obtaining time from a stratum 1 server; a stratum 3 server gets its time from a stratum 2 server, and so on. To avoid long-lived synchronization loops, the number of strata is limited to 15.

Stratum 2 (and higher) hosts might be company or campus servers that obtain time from some number of primary servers and provide time to many local clients. In general:

• Lower-strata hosts act as time servers.
• Higher-strata hosts are clients that adjust their time clocks according to the servers.

Internet time servers are usually stratum 1 servers. Other hosts connected to an internet time server have stratum numbers of 2 or higher and may act as time servers for other hosts on the network. Clients usually choose one of the lowest accessible stratum servers from which to synchronize.

12.1.2 How Hosts Negotiate Synchronization

Each host has its identifying stratum number encoded within UDP datagrams. Peers communicate by exchanging these timestamped UDP datagrams. NTP uses these exchanges to construct a list of possible synchronization sources then sorts them according to stratum and synchronization distance. Peers are accepted or rejected, leaving only the most accurate and precise sources.

NTP evaluates any new peer to determine whether it qualifies as a new (more suitable) synchronization source.

NTP rejects the peer under the following conditions:

• The peer is not synchronized.
• The stratum is higher than the current source's stratum.
• The peer is synchronized to the local node.

NTP accepts the peer under the following conditions:

• There is no current time source.
• The current source is unreachable.
• The current source is not synchronized
• The new source's stratum is lower than the current source.
• The new source's stratum is the same as the current source, but its distance is closer to the synchronization source by more than 50%.

The OpenVMS system clock is maintained as a software timer with a resolution of 100 nanoseconds, updated at 10-millisecond intervals. A clock update is triggered when a register, loaded with a predefined value, has decremented to zero. Upon reaching zero, an interrupt is triggered that reloads the register, thus repeating the process.

The smaller the value loaded into this register, the more quickly it reaches zero and triggers an update. The clock runs more quickly in such an instance. A larger value means more time between updates; therefore, the clock runs more slowly. A clock tick is the amount of time between clock updates.

12.1.4 How NTP Makes Adjustments to System Time

Once NTP has selected a suitable synchronization source, NTP compares the source's time with that of the local clock. If NTP determines that the local clock is running ahead of or behind the synchronization source, NTP uses a general drift mechanism to slow down or speed up the clock as needed. NTP accomplishes this by issuing a series of new clock ticks. For example, if NTP detects that the local clock is drifting ahead by +0.1884338 second, it issues a series of new ticks in an effort to reduce the difference between the synchronization source and the local clock.

If the local system time is not reasonably correct, NTP will not set the local clock. For example, if the new time is more than 1000 seconds off in either direction, NTP does not set the clock. In this case, NTP logs the error and shuts down.

NTP maintains a record of the resets it makes along with informational messages in the NTP log file, TCPIP$NTP_RUN.LOG. See Section 12.6 for more details about event logging and help in interpreting an NTP log file.

12.1.5 Configuring the Local Host

As the system manager of the local host, you determine which network hosts to use for synchronization and populate an NTP configuration file with a list of the participating hosts.

NTP hosts may be configured in one or more of the following modes:

• Client/server mode
  This mode indicates that the local host wants to obtain time from the remote server and is willing to supply time to the remote server if necessary. This mode is appropriate in configurations involving a number of redundant time servers interconnected through diverse network paths. Internet time servers generally use this mode.
  Indicate this mode with a peer declaration in the configuration file. For example:

  peer 18.72.0.3

• Client mode
  This mode indicates that the local host wants to obtain time from the remote server but it is not willing to provide time to the remote server. Client mode is appropriate for file server and workstation clients that do not provide synchronization to other local clients. A host with higher stratum generally uses this mode.
  Indicate client mode with the server declaration in the configuration file. For example:

  server 18.72.0.3

• Broadcast mode
  This mode indicates that the local server will send periodic broadcast messages to a client population at the broadcast/multicast address specified. This specification normally applies to the local server operating as a sender.
  Indicate this mode with a broadcast declaration in the configuration file. For example:

  broadcast 18.72.0.255

The NTP service can be shut down and started independently of TCP/IP Services. The following files are provided:

• SYS$STARTUP:TCPIP$NTP_STARTUP.COM allows you to start up the NTP service independently.
• SYS$STARTUP:TCPIP$NTP_SHUTDOWN.COM allows you to shut down the NTP service independently.

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services:

• SYS$STARTUP:TCPIP$NTP_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when the NTP service is started.
• SYS$STARTUP:TCPIP$NTP_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when the NTP service is shut down.

The NTP configuration file TCPIP$NTP.CONF contains a list of hosts your system will use for time synchronization. Before configuring your host, you must:

1. Select time sources.
2. Obtain the IP addresses or host names of the time sources.
3. Obtain the version number of NTP that the hosts are running.

To ensure reliable synchronization, select multiple time sources that you are certain provide accurate time and are synchronized to an Internet time server.

To minimize common points of failure, avoid synchronizing:

• The local host to another peer at the same stratum unless the latter is receiving time from a lower stratum source to which the local host cannot connect
• More than one host in a particular administrative domain to the same time server outside that domain

To simplify configuration file maintenance, avoid configuring peer associations with higher stratum servers.

12.3.1 Creating the Configuration File

To create a configuration file for your local host, edit a copy of the file TCPIP$NTP.TEMPLATE (located in SYS$SPECIFIC:[TCPIP$NTP]) to add the names of participating hosts, then save the file as SYS$SPECIFIC:[TCPIP$NTP]TCPIP$NTP.CONF. This file is not overwritten when you install subsequent versions of TCP/IP Services.

NTP configuration statements are formatted as follows:

• peer address [key ID] [version number] [prefer] [minpoll interval] [maxpoll interval]
  server address [key ID] [version number] [prefer ]
  broadcast address [key ID] [version number] [ttl nn]
  The following table describes the options to these statements:

  Option	Description
  key ID	For all packets sent to the address, includes authentication fields encrypted using the specified key identifier, an unsigned 32-bit integer. The default is no encryption.
  version number	Specifies the version number to be used for outgoing NTP packets. Versions 1, 2, and 3 are the choices. The default is 3.
  prefer	Marks the server as preferred. This host will be chosen for synchronization among a set of correctly operating hosts.
  minpoll interval	Specifies the minimum polling interval for NTP messages, in seconds to the power of two. The allowable range is 4 (16 seconds) to 14 (16384 seconds), inclusive. This option is not applicable to reference clocks. The default is 6 (64 seconds).
  maxpoll interval	Specifies the maximum polling interval (in seconds), for NTP messages. The allowable range is 4 (16 seconds) to 14 (16384 seconds) inclusive. The default is 10 (1024 seconds). (This option does not apply to reference clocks.)
  ttl nn	Specifies the time-to-live for multicast packets. Used only with broadcast mode.

• broadcastclient address
  This statement directs the local server to listen for broadcast messages at the broadcast address of the local network. The default address is the subnet address with each host file bit set to 1. Upon hearing a broadcast message for the first time, the local server measures the nominal network delay using a brief client/server exchange with the remote server, then enters the broadcastclient mode, in which it listens for and synchronizes to succeeding broadcast messages. Note that, to avoid accidental or malicious disruption in this mode, both the local and remote servers should use authentication and the same trusted key and key identifier.
• multicastclient address
  This statement directs the local server to listen for multicast messages at the group address of the global network. This command operates like the broadcastclient command but uses IP multicasting.
• driftfile file-specification
  This statement specifies the name of the file used to record the frequency offset of the local clock oscillator. If the file exists, it is read at startup to set the initial frequency offset, and then is updated hourly with the current frequency computed by the NTP server.
  If the file does not exist or if the driftfile command is not specified in the configuration file, the initial frequency offset is assumed to be zero. If the file does not exist but the driftfile keyword is specified without a parameter, the default, SYS$SPECIFIC:[TCPIP$NTP]TCPIP$NTP.DRIFT, is used.
  In these cases, it may take some hours for the frequency to stabilize and the residual timing errors to subside.
  The drift file TCPIP$NTP.DRIFT consists of a single floating-point number, which records the frequency of the offset measured in parts per million (ppm).
• enable auth | bclient | monitor | pll | stats
  disable auth | bclient | monitor | pll | stats
  These statements enable and disable the following server options:

  auth	Controls synchronization with unconfigured peers only if the peer has been correctly authenticated using a trusted key and key identifier. By default, auth is enabled.
  bclient	Controls the server to listen for messages from broadcast or multicast servers. By default, bclient is disabled.
  monitor	Controls the monitoring facility. By default, monitor is enabled.
  pll	Controls whether the server adjusts its local clock by means of NTP. If disabled, the local clock free-runs at its intrinsic time and frequency offset. This flag is useful if the local clock is controlled by some other device or protocol and NTP is used only to provide synchronization to other clients. In this case, the local clock driver is used. By default, pll is enabled.
  stats	Enables the statistics facility. By default, stats is enabled.

TCP/IP Services NTP includes a comprehensive monitoring facility suitable for continuous, long term recording of server and client timekeeping performance. See the statistics command below for a listing and example of each type of statistics currently supported. Statistic files are managed using file generation sets and scripts.

You can specify the following monitoring commands in your configuration file:

• statistics name [ ... ]
  Enables writing of statistics records. The following is a list of the supported name statistics:
  • loopstats
    Enables recording of loop filter statistics information. Each update of the local clock outputs a line of the following form to the file generation set named loopstats :

    48773 10847.650 0.0001307 17.3478 2

    
    The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). (A Julian Day [JD] begins at noon and runs until the next noon. The JD number is the number of days [or part of a day] since noon [UTC] on January 1, 4713 B.C. A Modified Julian Day [MJD] is the JD minus 2,400,000.5.)
    The next three fields show time offset (in seconds), frequency offset (in parts per million) and time constant of the clock-discipline algorithm at each update of the clock.
  • peerstats
    Enables recording of peer statistics information. This includes statistics records of all peers of an NTP server and of special signals, where present and configured. Each valid update appends a line of the following form to the current element of a file generation set named peerstats :

    48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142

    
    The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next two fields show the peer address in dotted-quad notation and status, respectively. The status field is encoded in hexadecimal in the format described in Appendix A of the NTP specification (RFC 1305). The final three fields show the offset, delay, and dispersion (in seconds).
  • clockstats
    Enables recording of clock driver statistics information. Each update received from a clock driver outputs a line in the following form to the file generation set named clockstats :

    49213 525.624 127.127.4.1 93 226 00:08:29.606 D

    
    The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next field shows the clock address in dotted-quad notation, The final field shows the last timecode received from the clock in decoded ASCII format, where meaningful. In some clock drivers, a good deal of additional information can be gathered and displayed as well. See information specific to each clock for further details.
  • rawstats
    Enables recording of raw timestamps. Each valid update appends a line in the following form to the file generation set named rawstats :

    51554 79509.68 16.20.208.53 16.20.208.97 3156617109.664603 3156617109.673268 3156617109.673268 31 56617109.673268 3156617109.666556

    
    The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next two fields show the peer and local addresses in dotted-quad notation. The next four fields are:
    • The originate timestamp
    • The received timestamp
    • The transmitted timestamp (the last one sent to the same peer)
    • The timestamp of the packet's arrival on the server
  • statsdir directory-path
    Indicates the full path of a directory where statistics files should be created.

A sample of the NTP configuration template follows:

#             Copyright 2000 Compaq Computer Corporation
#
#                  Example NTP Configuration File
#
# Rename this template to TCPIP$NTP.CONF.
#
# See the Compaq TCP/IP Services for OpenVMS Management manual for
# additional commands and detailed instructions on using this
# configuration file.
#
# The Network Time Protocol (NTP) provides synchronized timekeeping among
# a set of distributed time servers and clients. The local OpenVMS host
# maintains an NTP configuration file, TCPIP$NTP.CONF, of participating peers.
# TCPIP$NTP.CONF is maintained in the SYS$SPECIFIC:[TCPIP$NTP] directory.
#
# As the system manager populating this file, you must determine the
# peer hosts with which the local hosts should negotiate and synchronize.
# Include at least one (but preferably three) hosts that you are
# certain have the following characteristics:
#
#       * provide accurate time
#       * synchronize to Internet Time Servers (if they are not themselves
#         Internet Time Servers)
#
# The NTP configuration file is not dynamic, and therefore requires
# restarting NTP  after being edited to make the changes take effect.
# However, you can make run-time configuration requests interactively
# using the TCPIP$NTPDC utility.

# Your NTP configuration file should always include the following
# driftfile entry.  The driftfile is the name of the file that stores
# the clock drift (also known as frequency error) of the system clock.

driftfile SYS$SPECIFIC:[TCPIP$NTP]TCPIP$NTP.DRIFT

# Sample peer entries follow.  Replace them with your own list of hosts
# and identify the appropriate association mode.  If you specify
# multiple hosts, NTP can choose the best source with which to
# synchronize. This also provides reliability in case one of the hosts
# becomes unavailable.

# Identify each peer with a fully qualified DNS host name or with
# an IP address in dotted-quad notation.

peer 18.72.0.3
peer 130.43.2.2
peer 16.1.0.22
peer parrot

# The following commands allow interoperation of NTP with another time service
# such as DTSS.  If enabled (by removing #), NTP will not set the system clock.

# server 127.127.1.0 prefer
# fudge 127.127.1.0 stratum 0

# The following commands allow this node to act as a backup NTP server (or as
# the sole NTP server on an isolated network), using its own system clock as
# the reference source.  If enabled (by removing #), this NTP server will
# become active only when all other normal synchronization sources are
# unavailable.

# server 127.127.1.0
# fudge 127.127.1.0 stratum 8