MultiNet V5.0 Install & Admin Guide

Appendix B

Network Time Protocol (XNTP)

MultiNet now includes version 4 of the NTP protocol. NTP version 2 software is no longer included in MultiNet. XNTP (NTP version 3) software is still included to ease the transition, but will be retired in a future release. NTP version 4 is backwards compatible with all prior versions of NTP, though it will only function with NTP version 1 in a client/server role, as peering is not supported with that version of the protocol. For information on the new NTP version 4 support, see the NTP chapter of this guide. This chapter descripes the older NTPv3 support, XNTP.

If you are still running NTP version 2 software, you will need to update your system to use XNTP. If you are running NTPv2 now, you must convert existing NETCONTROL parameters into the NTP.CONF file for use with XNTP. SeeConverting to the NTP.CONF File for instructions.

This chapter describes how to specify timezones and synchronize your system clock with that of a remote host using the Network Time Protocol version 3 (XNTP). To use XNTP, you need a connection to the Internet, or you must configure the system to use its own internal clock.

Timezone Configuration and Hardware Clock Overview	Loadable Timezone Rules
Timezone Support	XNTP Functions

Timezone Configuration and Hardware Clock Overview

By convention, the hardware clock is usually set to the local time, but network protocols represent time in Greenwich Mean Time (GMT), also known as Universal Coordinated Time (UTC).

To convert between local time and GMT, MultiNet uses built-in rules or rules provided by the system manager.

Each country or geographical area has its own names for timezones and its own rules for Daylight Savings Time (DST). The names for these timezones and rules are not necessarily unique; for example, "EST" could refer to the United States Eastern Standard Time, the Canadian Eastern Standard Time (which uses different DST rules), or the Australian Eastern Standard Time (which is a different offset from GMT as well).

MultiNet uses the name of the local timezone specified by a system manager to calculate the offset between the local time and GMT, so it is important that an appropriate set of timezone rules be selected for your area.

MultiNet assumes that the hardware clock is always set exactly to local time. For a smooth transition to and from Daylight Savings Time (DST), the hardware clock must be reset at the appropriate time.

Note! Using a military time zone or an explicit GMT offset disables automatic Daylight Savings Time transitions.

Timezone Support

Because it is impossible to consider every country or area in which MultiNet might be used, and because the Daylight Savings Time rules are subject to change by governmental action, MultiNet permits you to write your own site-specific timezone rules. There are two types of timezone rules-compiled-in and loaded rules.

• Compiled-in rules are geographically centered around the United States but also include foreign timezones whose names do not conflict with the U.S. timezones.

• Loadable rules are selected with the NET-CONFIG SET TIMEZONE-RULES command and can be used to override the compiled-in rules.

MultiNet includes a database of the most common loadable rules; you can select these rules as-is, or modify them to conform to the correct local timezone rules.

When MultiNet searches the timezone rules looking for a zone, it first searches the loaded rules in the order they are selected, then searches the compiled-in rules. This method allows you to change the compiled-in rules by loading rules that override them.

In addition to the standard one-letter U.S. military time zones and timezones of the form GMT+hh:mm or GMT-hh:mm, there are compiled-in timezone rules supported by MultiNet which are shown in Table B-1.

Table B-1 Compiled-In Timezone Rules

Timezone Name	GMT Offset	DST Rules	Area or Country
EST or EDT	-5 hours	U.S. Federal	Eastern United States
CST or CDT	-6 hours	U.S. Federal	Central United States
MST or MDT	-7 hours	U.S. Federal	Mountain United States
PST or PDT	-8 hours	U.S. Federal	Pacific United States
YST or YDT	-9 hours	U.S. Federal	Yukon
HST	-10	-none-	Hawaii
NST or NDT	-3:30 hours	Canadian	Canadian Newfoundland
AST or ADT	-4 hours	Canadian	Canadian Atlantic
JST	+9 hours	-none-	Japan
SST	+8 hours	-none-	Singapore
GMT	+0 hours	-none-	Greenwich Mean Time
GMT or BST	+0 hours	British	Britain
WET or WET-DST	+0 hours	European	Western Europe
MET or MET-DST	+1 hour	European	Middle Europe
CET or CET-DST	+1 hour	European	Central Europe (Middle Europe)
EET or EET-DST	+2 hours	European	Eastern Europe
NZST or NZDT	+12 hours	New Zealand	New Zealand

Loadable Timezone Rules

Loadable timezone rules provided with MultiNet are in the text file MULTINET:TIMEZONES.DAT. You can add user-written timezone rules to the file MULTINET:TIMEZONES.LOCAL to override the zones in TIMEZONES.DAT. Loadable timezone rules consist of three parts:

COUNTRY	Is a collection of timezones (ZONEs). For example, the country US selects all U.S. timezones. This provides a convenient way to select groups of timezones.
ZONE	Is a specification of a particular timezone, including the name of the zone, the GMT offset, the DST rules in effect, and the name to use while DST is in effect.
RULE	Is a rule for determining when DST is in effect.

Format of COUNTRY Specification

COUNTRY countryname zonename [zonename . . .]

The COUNTRY specification gives the name of a geographical area and the names of the timezones associated with it. This provides a way to group timezones so they may be selected more conveniently.

The following example shows the definition of the country "US" listing the zones corresponding to the United States. The example for Arizona is slightly different, showing the zone "US/Arizona" instead of "US/Mountain." ("US/Arizona" is the definition of a Mountain timezone that does not observe Daylight Savings Time.)

Country US US/Eastern US/Central US/Mountain US/Pacific US/Yukon US/Hawaii

Country US/Arizona -

US/Eastern US/Central US/Arizona US/Pacific US/Yukon US/Hawaii

Format of ZONE Specification

ZONE zonename gmtoffset rulename standar

zonename	Is the name by which this zone can be selected, or the name by which it is referred to in a COUNTRY specification.
gmtoffset	Is this zone's standard time offset from GMT.
rulename	Is the name of the RULE specification that determines when DST is in effect for this zone. The rulename may be an underscore (_) to indicate that this zone does not use DST.
standard-name and dst-name	Are the names by which this zone is referred to during standard time, and during Daylight Savings Time, respectively. These are the names by which SET TIMEZONE selects the local timezone.

d-name dst-name [COMPILED_IN]

The ZONE specification describes a timezone:

If there are no DST rules, the dst-name should be specified as an underscore (_). The optional COMPILED_IN keyword indicates that this rule is compiled-in and need not be loaded, as long as no other rules conflict with it. If you edit a COMPILED_IN ZONE specification, you must remove the COMPILED_IN keyword to force the ZONE specification to be loaded.

The following example shows the definition of the normal United States Mountain timezone. The Arizona example shows the definition of a Mountain timezone that does not observe Daylight Savings Time.

Zone US/Mountain -7:00 US MST MDT COMPILED_IN
Zone US/Arizona -7:00 _ MST

Format of RULE Specification

RULE rulename startyear ruletype save start-date end-date

The RULE specification describes a set of rules for determining at what times DST is in effect:

rulename	Is the name of the RULE specification in ZONE specifications.
startyear	Is the year during which this DST rule takes effect. The rule remains in effect until a later startyear is specified in a rule with the name rulename.
ruletype	Specifies the type of DST rules. There are three permitted values: • DST indicates normal Northern-Hemisphere Daylight Savings Time rules, which switch at the time and date indicated. • REV_DST indicates normal Southern-Hemisphere Daylight Savings Time rules. NULL indicates that no Daylight Savings Time is in effect during the specified years.
save	Indicates the difference between Standard Time and DST.
start-date and end-date	Specify the starting and ending dates for DST. Specific dates can be specified, or rules such as "First Sunday" or "Last Sunday" can be used. See the file MULTINET:TIMEZONES.DAT for examples on specifying dates.

The following example illustrates the United States Federal Daylight Savings Time rules:

Rule US 1987 DST 1:00  First Sunday April 2:00 Last Sunday October 2:00

Rule US 1976 DST 1:00  Last  Sunday April 2:00 Last Sunday October 2:00

Rule US 1975 DST 1:00  23    February     2:00 Last Sunday October 2:00

Rule US 1974 DST 1:00  6     January      2:00 Last Sunday October 2:00

Rule US 1970 DST 1:00  Last  Sunday April 2:00 Last Sunday October 2:00

Loadable Timezone Rules Provided with MultiNet

Table B-2 shows the loadable rules provided in the MULTINET:TIMEZONES.DAT file which you may modify or augment as appropriate for your location.

Table B-2 Loadable Timezone Rules

Country Name	Rule Name	Timezone Name	GMT Offset	DST Rules
	GMT	GMT [ This timezone is compiled-in also.]	0 hours	-none-
	UT	UTa	0 hours	-none-
US-Military	US-Military/Za	Z	0 hours	-none-
US-Military	US-Military/Aa	A	-1 hour	-none-
US-Military	US-Military/Ba	B	-2 hours	-none-
US-Military	US-Military/Ca	C	-3 hours	-none-
US-Military	US-Military/Da	D	-4 hours	-none-
US-Military	US-Military/Ea	E	-5 hours	-none-
US-Military	US-Military/Fa	F	-6 hours	-none-
US-Military	US-Military/Ga	G	-7 hours	-none-
US-Military	US-Military/Ha	H	-8 hours	-none-
US-Military	US-Military/Ia	I	-9 hours	-none-
US-Military	US-Military/Ka	K	-10 hours	-none-
US-Military	US-Military/La	L	-11 hours	-none-
US-Military	US-Military/Ma	M	-12 hours	-none-
US-Military	US-Military/Na	N	1 hour	-none-
US-Military	US-Military/Oa	O	2 hours	-none-
US-Military	US-Military/Pa	P	3 hours	-none-
US-Military	US-Military/Qa	Q	4 hours	-none-
US-Military	US-Military/Ra	R	5 hours	-none-
US-Military	US-Military/Sa	S	6 hours	-none-
US-Military	US-Military/Ta	T	7 hours	-none-
US-Military	US-Military/Ua	U	8 hours	-none-
US-Military	US-Military/Va	V	9 hours	-none-
US-Military	US-Military/Wa	W	10 hours	-none-
US-Military	US-Military/Xa	X	11 hours	-none-
US-Military	US-Military/Ya	Y	12 hours	-none-
US	US/Easterna	EST/EDT	-5 hours	US Federal
US	US/Centrala	CST/CDT	-6 hours	US Federal
US	US/Mountaina	MST/MDT	-7 hours	US Federal
US	US/Pacifica	PST/PDT	-8 hours	US Federal
US	US/Yukona	YST/YDT	-9 hours	US Federal
US	US/Hawaiia	HST	-10 hours	-none-
US/East-Indiana	US/East-Indiana	EST	-5 hours	-none-
US/Arizona	US/Arizona	MST	-7 hours	-none-
Canada	Canada/Newfoundlanda	NST/NDT	-3:30 hours	Canadian
Canada	Canada/Atlantica	AST/ADT	-4 hours	Canadian
Canada	Canada/Eastern	EST/EDT	-5 hours	Canadian
Canada	Canada/Central	CST/CDT	-6 hours	Canadian
Canada	Canada/Mountain	MST/MDT	-7 hours	Canadian
Canada	Canada/Pacific	PST/PDT	-8 hours	Canadian
Canada	Canada/Yukon	YST/YDT	-9 hours	Canadian
Canada	Canada/Saskatchewan	CST	-6 hours	-none-
Israel	Israel	IST/DST	+2 hours	Israeli
Australia	Australia/Tasmania	EST	10 hours	Australian
Australia	Australia/Queensland	EST	10 hours	-none-
Australia	Australia/North	CST	9:30 hours	-none-
Australia	Australia/West	WST	8 hours	-none-
Australia	Australia/South	CST	9:30 hours	Australian
Australia	Australia/Victoria	CST	10 hours	Australian
Australia	Australia/NSW	CST	10 hours	Australian
Australia	Australia/Yarcowinna	CST	9:30 hours	Australian
Australia	Australia/LHI	CST	10:30 hours	Australian
Europe	Britaina	GMT/BST	0 hours	GB-Eire
Europe	Europe/Westerna	WET/WET-DST	0 hours	W-Eur
Europe	Europe/Middlea	MET/MET-DST	1 hour	M-Eur
Europe	Europe/Centrala	CET/CET-DST	1 hour	M-Eur
Europe	Europe/Easterna	EET/EET-DST	2 hours	E-Eur
	Iceland	GMT	1 hour	-none-
	Poland	MET	1 hour	W-Eur
	Turkey	EET/EET/DST	3 hours	Turkey
Japan	Japana	JST	+9 hours	-none-
Singapore	Singaporea	SST	+8 hours	-none-
NewZealand	NewZealanda	NZST/NZDT	+12 hours	New Zealand

Selecting Timezone Rules

You select timezone rules and the local timezone as part of the MultiNet system startup command file, MULTINET:START_MULTINET.COM. You can use the MultiNet NET-CONFIG utility to specify the local timezone and which rules to load using the SET TIMEZONE and SET TIMEZONE-RULES commands. The following example shows how to select the United States Arizona rules and the local timezone MST:

$ MULTINET CONFIGURE
NET-CONFIG>SET TIMEZONE MST
NET-CONFIG>SET TIMEZONE-RULES US/ARIZONA
NET-CONFIG>

Configuring and Managing NTP

This section describes how to configure and manage the Network Time Protocol version 3 (XNTP) to synchronize timekeeping among a set of distributed time servers and clients. The synchronization is totally transparent to users.

MultiNet’s XNTP also includes two standard query programs, XNTPQ and XNTPDC, the utility XNTPTRACE, and the XNTPDATE program.

MultiNet’s XNTP implementation is based on Network Time Protocol Version 3 from David L. Mills and the University of Delaware, and complies with RFC 1305. (Copyright information is included on the verso of the title page of this guide.) The following sections are discussed:

• XNTP functions

• Implementing XNTP

• Timekeeping hosts

• Determining peer hosts

• Basic configuration commands

• Advanced configuration

• Basic configuration example

• Troubleshooting XNTP

• XNTPQ

• XNTPDC

• XNTPDATE

• XNTPTRACE

XNTP Functions

The Network Time Protocol version 3 (XNTP) is used to synchronize the time of a computer client or server to another server or reference time source, such as a radio, satellite receiver, or modem. It is accurate typically within a millisecond on LANs and up to a few tens of milliseconds on WANs, relative to Coordinated Universal Time (UTC), as provided by a Global Positioning Service (GPS) receiver. Typical XNTP configurations use multiple redundant servers and diverse network paths to achieve high accuracy and reliability. MultiNet’s XNTP implementation also supports cryptographic authentication to prevent accidental or malicious protocol attacks.

Synchronized timekeeping involves resolving the frequency difference (or skew) and time difference (or offset) between clocks in the network. The goal is for hosts to have accurate system time stamps and send accurate time quotes to each other. XNTP produces the following data and uses it in its synchronization effort:

Clock offset	Amount to adjust the local clock with the reference clock
Round trip delay	Ability of the local host to send a message to the reference clock so that it arrives at a certain time
Dispersion	Maximum error of the local clock relative to the reference clock

Timekeeping systems are judged based on the following criteria:

Stability	How well a clock can maintain a constant frequency
Accuracy	How well a clock’s time compares with national standards
Precision	How precisely a timekeeping system can maintain stability and accuracy
Reliability	How long a timekeeping system is connected and operational

XNTP makes local system time adjustments by either slewing or stepping the clock. Slewing runs the clock faster or slower than its normal frequency to keep the clock at the correct time. Stepping sets the clock immediately to the correct time. Stepping occurs very infrequently, only when there is a large time error to adjust, such as when starting XNTPD or when making daylight savings time (DST) changes.

NTP data is exchanged periodically between hosts as encapsulated in UDP datagrams, and adjustments are made based on an XNTP algorithm. The frequency of exchange is related to the effort required to synchronize the clocks. Whereas resolving a clock offset may take no more than a few exchanges, resolving skew and maintaining local time to within a millisecond can take hours and dozens of measurements. However, the frequency of exchange is rarely intrusive to normal network operation. Also, the unreliability of UDP has no measurable impact on the process, and the process does not depend on any such reliability.

Synchronized hosts, known as peers, are either time servers or clients. Peers are identified by relative NTP strata numbers. Lower strata peers act as time servers while higher strata peers are clients who adjust their time clocks according to these servers. An Internet Time Server (ITS) on the network is assigned stratum 1 because it has radio-clock-generated time based on Universal Coordinated Time (UTC). NTP peers can be (and often are) other types of systems running NTP, not just OpenVMS systems.

Each host has its identifying stratum number encoded within the UDP datagram. This means that hosts can effectively negotiate server and client roles.

The stratum method allows for backup timekeeping in case a node or connection goes down, and stratum numbers may change as a consequence. In Figure B-1 (a), each node has a stratum number based on hop count, with the ITS at the top of the pyramid. The solid arrows are the active synchronization paths and direction of timing information flow; the lighter arrows are background synchronization paths where timing information is exchanged but not necessarily used for synchronization. Figure B-1 (b) shows the same network with one of the connections broken — note that the stratum for the affected peer increases from 2 to 3.

Figure B-1 Synchronization Through Strata

NTP Files

XNTP uses the following files:

NTP.CONF	You maintain an XNTP configuration file, MULTINET:NTP.CONF, of participating peers. You determine the peer hosts with which the local host should negotiate and synchronize, then populate the file with a list of these peers, some of which may be at a higher or lower stratum than the local host. To add stability, multiple NTP servers (systems at a lower stratum) should show up as peers. You need to restart XNTP after you edit the NTP.CONF file.
NTP.KEYS	You maintain a MULTINET:NTP.KEYS file if access authorization is desired. (SeeAuthentication Using a Keys File.)
NTPSERVER.LOG	The XNTPD server outputs log information to the MULTINET:XNTPD.LOG file. (SeeTroubleshooting Tips.)
NTP.DRIFT	The MULTINET:NTP.DRIFT file consists of a single line containing a floating point number that records the frequency offset, measured in parts-per-million (PPM). XNTP updates this file once an hour to maintain an accurate frequency offset when restarting the XNTP service. You should not need to modify this file.

Implementing NTP

To implement XNTP:

1 Determine the hosts (peers) with which the local system should negotiate for synchronization. (SeeTimekeeping Hosts andDetermining Peer Hosts.)

2 Configure the NTP configuration file by adding these peers to it.

3 Use one of the query programs.

Converting to the NTP.CONF File

If you want to convert existing NTPv2 NETCONTROL parameters to the NTP.CONF file for XNTP under MultiNet 5.0 or later, you will have to do it manually. The CONVNTP.COM procedure included in prior versions of MultiNet to do this automatically is not supported in versions of MultiNet that include NTPv4 support (MultiNet 5.0 and later). If you want to convert automatically, you should not upgrade directly to MultiNet v5.0, but upgrade to a prior version first, convert your NTPv2 configuration, then upgrade to the latest release.

The following conversions need to be made:

NTPv2 parameter	XNTP keyword	XNTP file
peer	peer	NTP.CONF
passive	peer	NTP.CONF
server	server	NTP.CONF
trusting	trustedkey	NTP.KEYS

If the "configuration-file" parameter is encountered you should examine the associated file to see if any of the contents need to be added to the new NTP.CONF file:

All other NTPv2 parameters may be ignored.

A system running XNTP will interact with other systems, either clients, servers, or peers that are running NTP just fine. NTP servers/clients exchange version information with each other and operate with the lowest common denominator. Note that XNTP is still on the distribution, but Process Software encourages the conversion of XNTP to NTPv4 for all customers. NTPv2 is no longer included in MultiNet. Keeping XNTP for the current release was done to avoid having to make an immediate and total cutover all at once for all systems. While NTPv4 is functionally compatible with XNTP, there are some command and option file differences and we have tried to minimize disruption for those upgrading to the latest release.

Timekeeping Hosts

Internet Time Servers (ITSs) connected to accurate radio clocks maintain timekeeping on the Internet. These ITSs are at the absolute lowest level, or stratum 1, of the NTP network. Most timekeeping hosts on a specific network are at stratum 2 or higher. The NTP hosts negotiate for accurate time by exchanging NTP packets to determine:

1 The stratum each host is on (and, therefore, which one is the time server).

2 The time offset, so that the local host can adjust its time accordingly.

All NTP times are an offset of Universal Coordinated Time (UTC), formerly Greenwich Mean Time (GMT).

Determining Peer Hosts

Determine which list of peers you want to include in the configuration file. These are hosts with which you regularly exchange data and where accurate time coordination is an important factor. Include at least one (but preferably two) peer hosts that you are assured:

• Provide accurate time

• Synchronize to ITSs (if they are not themselves ITSs)

Two hosts provide reliability in case one goes down. You do not need to identify what stratum each peer is on. XNTP determines this through the reference information it sends in its UDP packet exchanges.

A list of public NTP servers, along with guidelines for their use, has typically been available at the following Web site:

http://www.eecis.udel.edu/~mills/ntp/servers.html.

Basic Configuration Commands

peer address [ key key ] [ version version ] [ prefer ]
server address [ key key ] [ version version ] [ prefer ] [ mode mode ]
broadcast address [ key key ] [ version version ] [ ttl ttl ]

These three commands specify the time server address to be used and the mode in which to operate. The address can be a domain name or an IP address in dotted quad notation.

Command	Specifies that the local server is to operate in...
peer	Symmetric active mode with the remote server. In this mode, the local server can be synchronized to the remote server and, in addition, the remote server can be synchronized by the local server. This is useful in a network of servers where, depending on various failure scenarios, either the local or remote server may be the better source of time.
server	Client mode with the specified remote server. In this mode, the local server can be synchronized to the remote server, but the remote server can never be synchronized to the local server.
broadcast	Broadcast mode, where the local server sends periodic broadcast messages to a client population at the broadcast/multicast address specified. Ordinarily, this specification applies only to the local server operating as a sender; for operation as a broadcast client, see the broadcastclient command that follows. In this mode, address is usually the broadcast address on (one of) the local networks.

The peer, server, and broadcast options include:

Option	Description
key key	All packets sent to an address are to include authentication fields encrypted using the specified key identifier, which is an unsigned 32-bit integer. The default is to not include an encryption field.
version version	Specifies the version number to be used for outgoing NTP packets. Versions 1, 2, and 3 are the choices, with version 3 the default.
prefer	Marks the server as preferred. The host is chosen for synchronization among a set of correctly operating hosts.
ttl ttl	This option is used only with broadcast mode. It specifies the number of routers to pass through before the packet is discarded. The default is 127 routers.

master-clock stratum

The master-clock command should be used to configure a host that has special hardware to synchronize its clock, or that has its time synchronized by an outside source such as the HP Time Synchronization Service (CTSS). XNTP propagates time information normally, but makes no changes to system time. A master clock would normally be configured at stratum 0 to 8. However, unless the local clock is reliably disciplined by an outside source, a low stratum may disrupt access by other clients to reliable NTP servers.

local-master stratum

The local-master command should be used for sites not connected to the Internet, or for the purpose of having a backup time source when all normal synchronization sources are unavailable. This allows a machine to use its local clock as a time source while XNTP makes changes to system time to compensate for the clock’s frequency error. Specify a stratum number between 8 and 15.

broadcastclient

This command directs the local server to listen for broadcast messages at the broadcast address of the local network. The address is the subnet address with the host field bits set to ones. 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! In order to avoid accidental or malicious disruption in this mode, both the local and remote servers should operate using authentication and the same trusted key and key identifier.

slewalways

XNTPD normally steps the clock when there is a relatively large time error to adjust. The slewalways command directs the local XNTP server to always slew the clock. This command is useful to avoid an abrupt one hour clock change when daylight savings time (DST) changes occur. For DST changes when slewalways is specified, XNTPD slews the clock over a period of about 10 hours.

{ enable | disable } auth

Enables the server to synchronize with unconfigured peers only if the peer was correctly authenticated using a trusted key and key identifier. (SeeAuthentication Using a Keys File.) The default for this flag is disable.

{ enable | disable } monitor

Enables the monitoring facility. See the monlist command of the XNTPDC program for further information. The default for this flag is enable.

{ enable | disable } stats

Enables the statistics facility. For further information, seeMonitoring Commands. The default for this flag is enable.

{ enable | disable } opcom

Enables OPCOM messaging for XNTP. The default for this flag is enable.

Advanced Configuration

Advanced configuration involves configuring a keys file for authentication, viewing statistics, and using access control and various miscellaneous commands.

Authentication Using a Keys File

The NTP standard specifies an extension which provides cryptographic authentication of received NTP packets. This is implemented in XNTPD using the MD5 algorithm to compute a digital signature, or message digest. The specification allows any one of possibly four billion keys, numbered with 32-bit key identifiers, to be used to authenticate an association. 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 the file MULTINET:NTP.KEYS, which should be exchanged and stored using secure procedures. There are three classes of keys involved in the current implementation. One class is used for ordinary NTP associations, another for the XNTPQ utility program, and the third for the XNTPDC utility program.

trustedkey key [ ... ]

Specifies the encryption key identifiers which are trusted for the purposes of authenticating peers suitable for synchronization. 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.

Note! NTP key 0 is fixed and globally known. If meaningful authentication is to be performed, the 0 key should not be trusted.

requestkey key

Specifies the key identifier to use with the XNTPDC program, which uses a proprietary protocol specific to this distribution of XNTPD. The key argument to this command is a 32-bit unsigned integer. If no requestkey command is included in the configuration file, or if the keys do not match, such requests are ignored.

controlkey key

Specifies the key identifier to use with the XNTPQ program, which uses the standard protocol defined in RFC 1305. The key argument to this command is a 32-bit unsigned integer. If no requestkey command is included in the configuration file, or if the keys do not match, such requests are ignored.

Key File Format

For MD5, keys are 64 bits (8 bytes), read from the MULTINET:NTP.KEYS file. While key number 0 is fixed by the NTP standard (as 64 zero bits) and may not be changed, one or more of the keys numbered 1 through 15 may be arbitrarily set in the keys file.

The keys file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form:

keyno type key

• keyno is a positive integer

• type is a single character M for the MD5 key format

• key is the key itself

The key is a one-to eight-character ASCII string using the MD5 authentication scheme.

Note! Both the keys and the authentication schemes (MD5 or DES) must be identical between a set of peers sharing the same key number.

Note! The keys used by the XNTPQ and XNTPDC programs are checked against passwords requested by the programs and entered by hand.

Monitoring Commands

XNTP includes a comprehensive monitoring facility suitable for continuous, long term recording of server and client timekeeping performance. (See the statistics command that follows for a listing and example of each type of statistic currently supported.) The monitoring commands are as follows:

statistics { loopstats | peerstats | clockstats } [ ... ]

Enables writing of statistics records. Currently, three kinds of statistics are supported:

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). 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 a 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 hex in the format described in Appendix B.2.2 of the NTP specification RFC 1305. The final three fields show the offset, delay, and dispersion, all in seconds.
rawstats	Enables recording of raw peer statistics information. Each update of the local clock outputs a line of the following form to the file generation set named rawstats: 50528 68596.786 192.42.95.1 198.115.142.54 3067959784.942463 3067961504.783990 3067961504.783990 3067959784.946858 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 address in dotted quad notation. The final four fields show the time stamps for a peer NTP communication.

statsdir directory-path

Indicates the full path of a directory where statistics files should be created. This keyword allows the (otherwise constant) filegen filename prefix to be modified for file generation sets, which is useful for handling statistics logs.

filegen { loopstats | peerstats | clockstats } [ file filename ] [ type typename ] [ enable | disable ]

Configures setting of the generation fileset name. Generation filesets provide a means for handling files that are continuously growing during the lifetime of a server. Server statistics are a typical example for such files. Generation filesets provide access to a set of files used to store the actual data.

At most one element of the set is being written to at any one time. The type given specifies when and how data is directed to a new element of the set. This way, information stored in elements of a fileset that are currently unused are available for administrative operations without the risk of disturbing the operation of XNTPD. (Also, they can be removed to free space for new data produced.)

For the loopstats, peerstats, and clockstats parameters, see the statistics command.

The following additional parameters apply:

filename	This string is directly concatenated to the directory MULTINET: or the directory prefix specified using the statsdir option explained above. The suffix for this filename is generated according to the type of a fileset.
typename	A file generation set is characterized by type typename, with the following typenames: none One element of the fileset is used for each, NTPD server. day One file generation set element is created per day. A day is defined as the period between 00:00 and 24:00 UTC. The fileset member suffix consists of a dot (.) and a day specification in the form YYYYMMDD. YYYY is a 4-digit year number (such as 2003). MM is a two digit month number. DD is a two digit day number. Thus, all information written at 10 December 2002 would end up in a file named prefix filename.20021210. week Any fileset member contains data related to a certain week of a year. The term week is defined by computing day-of-year modulo 7. Elements of such a file generation set are distinguished by appending the following suffix to the fileset filename base: a dot, a 4-digit year number, the letter W, and a 2-digit week number. For example, information from January 10th, 2003 would end up in a file with suffix .2003W1. month One generation fileset element is generated per month. The filename suffix consists of a dot, a 4-digit year number, and a 2-digit month. year One generation file element is generated per year. The filename suffix consists of a dot and a 4-digit year number. age This type of file generation sets changes to a new element of the fileset every 24 hours of server operation. The filename suffix consists of a dot, the letter a, and an 8-digit number. This number is taken to be the number of seconds the server is running at the start of the corresponding 24-hour period.
enable and disable	Information is only written to a file generation by specifying enable; output is prevented by specifying disable.

Access Control Commands

XNTP implements a general purpose address- and mask-based restriction list. The list is sorted by address and by mask, and the list is searched in this order for matches, with the last match found defining the restriction flags associated with the incoming packets. The source address of incoming packets is used for the match, with the 32-bit address combined with the mask associated with the restriction entry and then compared with the entry’s address (which was also combined with the mask) to look for a match.

The restriction facility was implemented to conform with the access policies for the original NSFnet backbone time servers. While this facility may be otherwise useful for keeping unwanted or broken remote time servers from affecting your own, it should not be considered an alternative to the standard XNTP authentication facility. Source address based restrictions are easily circumvented by a determined hacker.

restrict numeric-address [ mask numeric-mask ] [ flag ] [ ... ]

The numeric-address argument, expressed in dotted quad form, is the address of a host or network. The mask argument, also expressed in dotted quad form, defaults to 255.255.255.255, meaning that the numeric-address is treated as the address of an individual host. A default entry (address 0.0.0.0, mask 0.0.0.0) is always included and, given the sort algorithm, is always the first entry in the list.

Note! While numeric-address is normally given in dotted-quad format, the text string default, with no mask option, can be used to indicate the default entry.

In the current implementation, flag always restricts access, such that an entry with no flags indicates that free access to the server is to be given. The flags are not orthogonal, in that more restrictive flags often make less restrictive ones redundant. The flags can generally be classed into two categories: those that restrict time service, and those that restrict informational queries and attempts to do run-time reconfiguration of the server. You can specify one or more of the following flags:

ignore	Ignores all packets from hosts which match this entry. If this flag is specified, neither queries nor time server polls are responded to.
noquery	Ignores all NTP mode 6 and 7 packets (information queries and configuration requests) from the source. Time service is not affected.
nomodify	Ignores all NTP mode 6 and 7 packets that attempt to modify the state of the server (run-time reconfiguration). Queries which return information are permitted.
noserve	Ignores NTP packets whose mode is other than 6 or 7. In effect, time service is denied, though queries may still be permitted.
nopeer	Provides stateless time service to polling hosts, but does not allocate peer memory resources to these hosts, even if they otherwise might be considered useful as future synchronization partners.
notrust	Treats these hosts normally in other respects, but never uses them as synchronization sources.
ntpport	This is actually a match algorithm modifier, rather than a restriction flag. Its presence causes the restriction entry to be matched only if the source port in the packet is the standard NTP UDP port (123).
limited	These hosts are subject to limitation of number of clients from the same net. Net in this context refers to the IP notion of net (class A, class B, class C, and so on). Only the first client_limit hosts (as set by the clientlimit command) that showed up at the server, and that were active during the last client_limit_period seconds (as set by the clientperiod command), are accepted. Requests from other clients from the same net are rejected. Only time request packets are taken into account. Query packets sent by the XNTPQ and XNTPDC programs are not subject to these limits. A history of clients is kept using the monitoring capability of XNTPD. Thus, monitoring is always active as long as there is a restriction entry with the limited flag.

Default restriction list entries, with the flags ignore, ntpport, for each of the local host’s interface addresses are inserted into the table at startup, to prevent the server from attempting to synchronize to its own time. However, a default entry is also always present if it is otherwise unconfigured. No flags are associated with the default entry (everything besides your own XNTP server is unrestricted).

clientlimit limit

Sets the client_limit variable that limits the number of simultaneous access-controlled clients. The default value is 3.

clientperiod period

Sets the client_limit_period variable that specifies the number of seconds after which a client is considered inactive and thus no longer is counted for client limit restriction. The default value is 3600 seconds.

Miscellaneous Command

setvar name[=value ] [ default ]

This command adds an additional system variable. These variables can be used to distribute additional information such as the access policy. If the variable of the form name = value is followed by the default keyword, the variable is listed as part of the default system variables (xntpq rv command). These additional variables serve informational purposes only. They are not related to the protocol other than that they can be listed. The known protocol variables always override any variables defined using the setvar mechanism.

Basic Configuration Example

Figure B-2 shows a highly redundant and robust configuration with multiple levels of backups. On the Internet close to your network, you have host 192.168.34.1 running at stratum 1, and 192.168.34.2 at stratum 2. In-house, you have host 192.168.67.1 synchronized with a radio clock and configured as a stratum 1 master clock.

Figure B-2 Sample NTP Configuration

As backup servers, you have two hosts, 192.168.67.2 and 192.168.67.3, in the climate-controlled room, one configured at stratum 10 and the other at 12. All other workstations on the floor point to these three servers as their synchronization source. When everything is running, every local host is synchronized to 192.168.67.1, since it is closer than Internet host 192.168.34.1. All the machines (peers) run at stratum 2.

If internal host 192.168.67.1 goes down and the Internet connection is still up, either Internet host 192.168.34.1 or 192.168.34.2 is selected depending on its availability, and the backup servers, 192.168.67.2 and 192.168.67.3, run at stratum 2 or 3, depending on which Internet host was selected. The peers synchronize off 192.168.67.2 or 192.168.67.3 at stratum 3 or 4, again depending on which Internet host was selected.

With 192.168.67.1 still unavailable and the Internet connection lost or all the Internet servers unavailable, 192.168.67.2 runs at stratum 10, since it was configured that way as a local clock. It then becomes the lowest stratum number in the network and all other hosts (including 192.168.67.3) are synchronized to it at stratum 11.

If 192.168.67.2 goes down, 192.168.67.3 runs at stratum 12 and all other hosts synchronize at stratum 13. It is important to set the stratum of 192.168.67.3 to 12. If set to 11, it might have a problem synchronizing to 192.168.67.2, since it may try to synchronize off it but finds it has the same stratum value. 192.168.67.3 would rather synchronize to 192.168.67.2 than to itself.

Example B-1 shows the configuration file entries for each of the three local servers (the other local hosts would all be configured as peers). You do not need to explicitly identify the peer strata, and the order of items is irrelevant.

Example B-1 Sample Entries in the Host NTP.CONF Files

; XNTP Configuration on 192.168.67.1

master-clock 1



; XNTP Configuration on 192.168.67.2

local-master 10

server 192.168.67.1

server 192.168.34.1

server 192.168.34.2

peer 192.168.67.3





; XNTP Configuration on 192.168.67.3

local-master 12

server 192.168.67.1

server 192.168.34.1

server 192.168.34.2

peer 192.168.67.2





; XNTP Configuration for Computer Room Host 192.168.67.x

server 192.168.67.1

server 192.168.67.2

server 192.168.67.3

peer 192.168.67.y

peer 192.168.67.z

.

.

.

Troubleshooting

XNTP provides error messages for troubleshooting.

Note! You can also use XNTPQ to troubleshoot XNTP.

Troubleshooting Tips

Here are some troubleshooting tips:

• Make sure the entries in the XNTP configuration file MULTINET:NTP.CONF are correct. At the minimum, there must be a server or peer declaration for a machine that is reachable, and if authentication is enabled, set it up to properly authenticate NTP packets. This machine serving time must be connected either to lower stratum machines or to some reference time source.

• Make sure that the logical MULTINET_TIMEZONE is properly defined to reflect the timezone (and daylight savings). If the logical is undefined or incorrect, XNTP is likely to abort. MULTINET_TIMEZONE should be set by configuring MultiNet with the configuration procedure MULTINET:CNFNET.COM by defining the MULTINET_TIMEZONE logical in one of the following ways:

• The MULTINET_TIMEZONE logical is defined by MultiNet when the system starts. If MultiNet has already been started, issuing the following command will temporarily redefine the logical:
MULTINET SET /TIMEZONE<zone name>/SELECT=<rule name>
However, the new value will not be preserved through a system reboot. To permanently change the value of this logical, the timezone rules must be configured using NETCONTROL according to the description on page 14-8 of the MultiNet v5.0 Administrator’s Guide.
However, NETCONTROL will not redefine the logical on the running system. If MultiNet has already been started, you have to do both.

• If using the slewalways command, make sure the system time is within 4000 seconds of the correct time before starting XNTPD. If the local system time is off by more than 4000 seconds from server time, XNTPD logs a message and stops running. Also, if the local clock is not within a minute or two of correct time when starting XNTPD with slewalways set, it may take some time for XNTPD to synchronize the clock. Ideally, set the clock with XNTPDATE or SET TIME before starting XNTPD.

• Make sure that TIMED and DTSS services are not running on the system. These services are used to synchronize time, and interfere with XNTP unless XNTP was configured in special cases to work with them. (See the master-clock command.)

The following messages are generated by the XNTP server. They go to both OPCOM and the MULTINET:XNTPD.LOG file. This log file is the best source of information for trouble- shooting in that it contains a record of these messages as well as additional informational messages. Messages appear in the log file without the bracketed prefix. There are four types of messages generated:

• Configuration messages

• Peer contact messages

• Synchronization messages

• Unexpected error condition messages

Troubleshooting Using XNTPQ

The XNTPQ utility has a few commands that are helpful in identifying problems. The peers command is one of the simplest and is a quick way to check the offset (time difference) between the local host and peer machines.

The readvar command is useful for more in depth information. Without arguments, it displays information about the local host. When readvar is followed by an assocID, it displays information about the peer corresponding to the assocID (use associations to display the assocIDs for all peers). Of interest is the record of time offsets and round trip delays for packets (the filtoffset and filtdelay fields). This provides a record of the last eight time updates obtained from a peer.

The command readvar assocID flash displays a useful variable, flash, which can be of particular interest for troubleshooting. The bits in the flash variable, if set, have the following meaning in relation to a peer:

0x01 /* duplicate packet received */
0x02 /* bogus packet received */
0x04 /* protocol unsynchronized */
0x08 /* peer delay/dispersion bounds check */
0x10 /* peer authentication failed */
0x20 /* peer clock unsynchronized */
0x40 /* peer stratum out of bounds */
0x80 /* root delay/dispersion bounds check */

XNTPQ, XNTPDC, XNTPDATE, and XNTPTRACE Utilities

The following sections describe the XNTPQ, XNTPDC, XNTPDATE, and XNTPTRACE utilities. These commands are available from the MULTINET command (i.e. "MULTINET XNTPDATE..."), or as DCL foreign command symbols through the use of the MULTINET:NTP_DEFINE.COM procedure. The same image is executed in either case and it is mostly a matter of personal preference which is used. You can define XNTP commands, NTP(v4) commands, or BOTH (the default), by use of a parameter to the procedure. The defined commands can be undefined, if desired, by use of the MULTINET:NTP_UNDEFINE.COM procedure, which takes the same parameter options.

Xntpq

The XNTPQ utility is used to query XNTP servers that implement the recommended NTP mode 6 control message format about current state and to request changes in that state. The program runs interactively or uses command line arguments. Requests to read and write arbitrary variables can be assembled, with output options available. XNTPQ can also obtain and print a list of peers in a common format by sending multiple queries to the server.

The utility uses NTP mode 6 packets to communicate with the XNTPD server, and hence can be used to query any compatible server on the network which permits it.

Note! Since NTP is a UDP protocol, this communication is somewhat unreliable, especially over large distances in terms of network topology. XNTPQ makes one attempt to retransmit requests, and times out requests if the remote host is not heard from within a suitable timeout time.

Interactive Commands

Internal Commands

Interactive format commands consist of a keyword followed by zero to four arguments. You may enter the minimum number of characters of the full keyword to uniquely identify the command. The output is normally sent to the standard output, but you can send the output to a file by appending a greater than (>) followed by a filename to the command line.

? [ command-keyword ] help [ command-keyword ]

A question mark (?) by itself prints a list of all the known command keywords. A question mark followed by a command keyword prints function and usage information.

cooked

Causes output from query commands to be "cooked" for user readability. Variables the server recognizes have their values reformatted for readability. Variables that XNTPQ determines should have a decodeable value, but do not, are marked with a trailing question mark (?).

host [ hostname ]

Sets the host to which future queries are sent. Hostname may be either a hostname or a numeric address. If hostname is omitted, the host currently set is displayed.

hostnames [ yes | no ]

If specifying hostnames yes (the default), hostnames are printed in information displays. If specifying hostnames no, numeric addresses are printed instead.

ntpversion [ 1 | 2 | 3 ]

Sets the NTP version number that XNTPQ claims in packets.

Note! Modes did not exist in NTP version 1. (There appears to be no servers left that demand version 1.) If the version value is omitted, the version number (default 3) currently in use is displayed.

quit

Exits XNTPQ.

raw

Causes all output from query commands to be printed as received from the remote server. The only formatting or interpretation done on the data is to transform non-ASCII data into a printable form.

timeout [ milliseconds ]

Specifies a timeout period for responses to server queries. The default is about 5000 milliseconds.

Note! Since XNTPQ retries each query once after a timeout, the total waiting time for a timeout is twice the timeout value set. If the milliseconds value is omitted, the current timeout period is displayed.

Control Message Commands

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 to which the values correspond by including its association ID. An association ID of 0 is special, and indicates the variables are system variables whose names are drawn from a separate name space.

associations

Obtains and prints a list of association identifiers and peer status for in-spec peers of the server being queried. Each line in the list is associated with the corresponding peer line given by the peers command. 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, as described in Appendix B.2.2 of the NTP specification RFC 1305. This is followed by a number of columns containing data decoded from the status word.

clockvar

Requests that a list of the server’s clock variables be sent. Servers that have a radio clock or other external synchronization respond in the affirmative to this. For a MultiNet XNTP server the request refers to the local clock, if configured for XNTPD by master-clock or local-master.

peers

Obtains a list of in-spec 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 ref ID is unknown); stratum of the remote peer; type of the peer (local, unicast, multicast, or broadcast), when the last packet was received; polling interval (in seconds); reachability register (in octal); and the current estimated delay, offset and dispersion of the peer (all in milliseconds). The character in the left margin indicates the fate of this peer in the clock selection process:

<space>	Discarded due to high stratum and/or failed sanity checks
x	Falseticker
.	Culled from the end of the candidate list
-	Discarded by the clustering algorithm
+	Included in the final selection set
#	Selected for synchronization but the distance exceeds the maximum
*	Selected for synchronization
o	Selected for synchronization, a PPS signal is in use

Note! Since the peers command depends on the ability to parse the values in the responses it gets, it may fail to work with servers that poorly control the data formats.

The contents of the host field may be in one of four forms. It may be a hostname, an IP address, a reference clock implementation name with its parameter or REFCLK(, ). With hostnames no, only IP addresses are displayed.

pstatus assocID

Sends a read status request to the server for the given association. (See the associations command for assocIDs). The names and values of the peer variables returned are printed.

Note! The status word from the header is displayed preceding the variables, both in hexidecimal and in English.

readvar [ assocID [ variable-name[=value ] [ ... ] ] ] rv [ assocID [ variable-name[=value ] [ ... ] ] ]

Requests that the values of the specified variables be returned by the server, by sending a read variables request. If you omit the association ID or give it as zero, the variables are system variables; otherwise they are peer variables and the values returned are those of the corresponding peer. (See the associations command for assocIDs). Omitting the variable list sends a request with no data, which should induce the server to return a default display. If more than one variable is requested, separate the variable list with commas and do not include spaces.

Command Line Format

ntpq [ -n ] [ -c command ] [ host ] [ ... ]

(If command line arguments are omitted, XNTPQ runs in interactive mode.)

-c

The command that follows is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). The command must be in double quotes if it consists of more than one word. Multiple -c options can be given.

-n

Displays all host addresses in dotted quad numeric format rather than converting them to canonical hostnames.

host

Sets the host to which future queries are sent, as either a hostname or a numeric address. If host is omitted, the local host is used.

xntpdc

The XNTPDC utility is used to query the XNTPD daemon about its current state and to request changes in that state. The program runs interactively or uses command line arguments. Extensive state and statistics information is available through the XNTPDC interface. In addition, nearly all the configuration options that can be specified at startup using XNTPD’s configuration file may also be specified at run-time using XNTPDC.

The XNTPDC utility uses NTP mode 7 packets to communicate with the XNTP server, and can be used to query any compatible server on the network which permits it.

Note! Since NTP is a UDP protocol, this communication is somewhat unreliable, especially over large distances, in terms of network topology. XNTPDC makes no attempt to retransmit requests, and times out requests if the remote host is not heard from within a suitable timeout time.

XNTPDC’s operation is specific to the XNTPD implementation and can be expected to work only with this, and possibly some previous versions, of the daemon. Requests from a remote XNTPDC program that affect the state of the local server must be authenticated, which requires both the remote program and local server to share a common key and key identifier.

Interactive Commands

Internal Commands

Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. The output of a command is normally sent to the standard output, but you can send the output of individual commands to a file by appending a greater than (>) followed by a filename to the command line.

? [ command-keyword ] help [ command-keyword ]

A question mark (?) by itself prints a list of all the known command keywords. A question mark (?) followed by a command keyword prints function and usage information.

delay milliseconds

Specifies a time interval to be added to timestamps included in requests that require authentication. This is used to enable unreliable server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized.

host [ hostname ]

Sets the host to which future queries are sent. Hostname may be either a hostname or a numeric address. If the hostname is omitted, the host currently set is displayed.

hostnames [ yes | no ]

If specified as hostnames yes (the default), hostnames are printed in information displays. If specified as hostnames no, numeric addresses are printed instead.

keyid [ keyid ]

Allows a key number to be used by XNTPDC to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose. If the keyid is omitted, the keyid currently set is displayed.

quit

Exits XNTPQ.

passwd

Prompts you to type in a password (which is not echoed) that is 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. If the keyid command was not used to set the keyid, you are prompted for the keyid.

timeout [ milliseconds ]

Specifies a timeout period for responses to server queries. The default is approximately 8000 milliseconds.

Note! Since XNTPDC retries each query once after a timeout, the total waiting time for a timeout is twice the timeout value set. If the milliseconds value is omitted, the current timeout period is displayed.

Control Message Commands

Query commands produce NTP mode 7 packets containing requests for information being sent to the server. These are read-only commands in that they make no modification of the server configuration state.

listpeers

Obtains and prints a brief list of the peers for which the server is maintaining state. These should 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 synchronization candidates.

peers

Obtains a list of peers for which the server is maintaining state, along with a summary of that state. Summary information includes the address of the remote peer; local interface address (0.0.0.0 if a local address has yet to be determined); stratum of the remote peer (a stratum of 16 indicates the remote peer is unsynchronized); polling interval (in seconds); reachability register (in octal); and current estimated delay, offset, and dispersion of the peer (all in seconds). In addition, the character in the left margin indicates the mode this peer entry is operating in:

+	Symmetric active
-	Symmetric passive
=	Remote server is being polled in client mode
^	Server is broadcasting to this address
~	Remote peer is sending broadcasts
*	Peer the server is currently synchronizing to

The contents of the host field may be in one of four forms: a hostname, IP address, reference clock implementation name with its parameter, or REFCLK (implementation number, parameter). With hostnames no, only IP-addresses are displayed.

showpeer peer-address [...]

Shows a detailed display of the current peer variables for one or more peers. Most of these values are described in the NTP Version 2 specification.

pstats peer-address [...]

Shows per-peer statistic counters associated with the specified peers.

loopinfo [ oneline | multiline ]

Prints the values of selected loop filter variables:

loop filter	is the part of NTP that deals with adjusting the local system clock
offset	is the last offset given to the loop filter by the packet processing code
frequency	is the frequency error of the local clock in parts per million (ppm)
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	is the number of seconds 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 printed, with multiline as the default.

sysinfo

Prints a variety of system state variables, such as the state related to the local server. All except the last four lines are described in the NTP Version 3 specification, RFC 1305.

The system flags can be set and cleared by the enable and disable configuration commands, respectively. These are the auth, bclient, monitor, pll, pps, and stats flags. (See the XNTPDC utility for the meaning of these flags.)

The stability is the residual frequency error remaining after the system frequency correction is applied, and is intended for maintenance and debugging. In most architectures, this value initially decreases from as high as 500 ppm to a nominal value in the range .01 to 0.1 ppm. If it remains high for some time after starting the daemon, something might be wrong with the local clock.

The broadcastdelay shows the default broadcast delay. The authdelay shows the default authentication delay, as computed by XNTPD for authorization.

sysstats

Prints statistics counters maintained in the protocol module.

memstats

Prints statistics counters related to memory allocation code.

iostats

Prints statistics counters maintained in the input-output module.

timerstats

Prints statistics counters maintained in the timer/event queue support code.

reslist

Obtains and prints the server’s restriction list. This list is usually printed in sorted order and may help to understand how the restrictions are applied.

monlist [ version ]

Obtains and prints traffic counts collected and maintained by the monitor facility. You do not normally need to specify the version number.

Runtime Configuration Requests

All requests that cause state changes in the server are authenticated by the server using the requestkey in the configuration file (which can be disabled by the server by not configuring a key). The key number and the corresponding key must also be made known to XTNPDC. This can be done using XNTPDC’s keyid and passwd commands, the latter of which prompts at the terminal for a password to use as the encryption key. You are also prompted automatically for both the key number and password the first time a command is given that would result in an authenticated request to the server. Authentication not only provides verification that the requester has permission to make such changes, but also gives an extra degree of protection against transmission errors.

Authenticated requests always include a timestamp in the packet data, which is included in the computation of the authentication code. This timestamp is compared by the server to its receive timestamp. If they differ by more than a small amount, the request is rejected. This is done for two reasons. First, it makes simple replay attacks on the server, by someone who might be able to overhear traffic on your LAN, much more difficult. Secondly, it makes it more difficult to request configuration changes to your server from topologically remote hosts. While the reconfiguration facility works well with a server on the local host, and may work adequately between time synchronized hosts on the same LAN, it works very poorly for more distant hosts. As such, if reasonable passwords are chosen, care is taken in the distribution and protection of keys, and appropriate source address restrictions are applied, the run-time reconfiguration facility should provide an adequate level of security. The following commands all make authenticated requests.

addpeer peer-address [ keyid ] [ version ] [ prefer ]

Adds a configured peer association at the given address and operates in symmetric active mode.

Note! An existing association with the same peer may be deleted when this command is executed, or may simply be converted to conform to the new configuration, as appropriate. If the optional keyid is a nonzero integer, all outgoing packets to the remote server have an authentication field attached, encrypted with this key. If the value is 0 (or not given), no authentication is done. The version can be 1, 2, or 3, and defaults to 3. The prefer keyword indicates a preferred peer (and thus is used primarily for clock synchronization if possible).

addserver peer-address [ keyid ] [ version ] [ prefer ]

Identical to the addpeer command, except that the operating mode is client.

broadcast peer-address [ keyid ] [ version ] [ prefer ]

Identical to the addpeer command, 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 XNTP. If using a multicast address, a multicast-capable kernel is required.

unconfig peer-address [...]

Removes the configured bit from the specified peers. In many cases, 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 ] [ ... ]

Operates the same as the enable and disable configuration file commands of XNTPD.

restrict address mask flag [ flag ]

Operates the same as the restrict configuration file commands of XNTPD.

unrestrict address mask flag [ flag ]

Unrestricts the matching entry from the restrict list.

delrestrict address mask [ ntpport ]

Deletes the matching entry from the restrict list.

readkeys

Causes the current set of authentication keys to be purged and a new set to be obtained by rereading the keys file (MULTINET:NTP.KEYS). This allows encryption keys to be changed without restarting the server.

trustedkey keyid [...] untrustedkey keyid [...]

Operates the same as the trustedkey and untrustedkey configuration file commands of XNTPD.

authinfo

Returns information concerning the authentication module, including known keys and counts of encryptions and decryptions which have been done.

reset

Clears the statistics counters in various modules of the server.

Command Line Format

xntpdc [ -n ] [ -c command ] [ host ] [ ... ]

Command Line Arguments

(If command line arguments are omitted, XNTPDC runs in interactive mode.)

-c

The command that follows is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). The command must be in double quotes if it consists of more than one word. Multiple -c options can be given.

-n

Displays all host addresses in dotted quad numeric format rather than converting them to canonical hostnames.

host

Sets the host to which future queries are sent, as either a hostname or a numeric address. If host is omitted, the local host is used.

ntpdate

The NTPDATE utility sets the local date and time, by polling the NTP servers given as the server arguments, to determine the correct time. A number of samples are obtained from each of the servers specified and a subset of the XNTP clock filter and selection algorithms are applied to select the best of these.

Note! The accuracy and reliability of ntpdate depends on the number of servers, the number of polls each time it is run, and the interval between runs.

The XNTPDATE utility can be run manually as necessary to set the host clock, or it can be run from the system startup command file to set the clock at boot time. This is useful in some cases to set the clock initially before starting the XNTP daemon, XNTPD. It is also possible to run XNTPDATE from a batch job. However, it is important to note that XNTPDATE with contrived batch jobs is no substitute for the XNTP daemon, which uses sophisticated algorithms to maximize accuracy and reliability while minimizing resource use. Finally, since XNTPDATE does not discipline the host clock frequency as does XNTPD, the accuracy using XNTPDATE is limited.

The XNTPDATE utility makes time adjustments in one of two ways. If it determines that the clock is wrong by more than 0.5 second, it simply steps the time by calling the $SETIME system service. If the error is less than 0.5 seconds, it slews the time by temporarily adjusting system clock variables. The latter technique is less disruptive and more accurate when the error is small, and works quite well when XNTPDATE is run by a batch job every hour or two.

The XNTPDATE utility declines to set the date if XNTPD is running on the same host. When running XNTPDATE every hour or two from a batch job, as an alternative to running XNTPD, results in precise enough timekeeping to avoid stepping the clock.

Format

xntpdate [-bdqsv] [-a key#] [-e delay] [-k file] [-p samples] [-o version#] [-t timeo] [server]

Command Line Options

-a key

Enables the authentication function and specifies the key identifier to be used for authentication as the argument key. The keys and key identifiers must match in both the client and server key files. The default is to disable the authentication function.

-B

Force the time to always be slewed, even if the measured offset is greater than ~128 ms. The default is to step the time if the offset is greater than ~128 ms.

Note! If the offset is much greater than ~128 ms in this case, that it can take several hours to slew the clock to the correct value. During this time, the host should not be used to synchronize clients.

-b

Force the time to be stepped, rather than slewed (default). This option should be used when called from a startup file at boot time.

-k keyfile

Specifies the path for the authentication key file as the string keyfile. The default is MULTINET:NTP.KEYS. This file should be in the format described for XNTPD configuration.

-o version

Specifies the NTP version for outgoing packets as the integer version, which can be 1 or 2. The default is 3. This allows XNTPDATE to be used with older NTP versions.

-p samples

Specifies the number of samples to be acquired from each server as the integer samples, with values from 1 to 8 inclusive. The default is 4.

-s

Enables OPCOM messaging. This is designed primarily for the convenience of batch jobs.

-t timeout

Specifies the maximum time waiting for a server response as the value timeout, in seconds and fraction. The value is rounded to a multiple of 0.2 seconds. The default is 1 second, a value suitable for polling across a LAN.

-u

Directs XNTPDATE to use an unprivileged port on outgoing packets. This is most useful when behind a firewall that blocks incoming traffic to privileged ports, and you want to synchronize with hosts beyond the firewall.

xntptrace

The XNTPTRACE utility determines where a given XNTP server gets its time from, and follows the chain of NTP servers back to their master time source. If given no arguments, it starts with localhost. Here is an example of the output from XNTPTRACE:

$ xntptrace
localhost: stratum 4, offset 0.0019529, synch distance 0.144135
server2ozo.com: stratum 2, offset 0.0124263, synch distance 0.115784
usndh.edu: stratum 1, offset 0.0019298, synch distance 0.011993, refid
’WWVB’

On each line, the fields are (left to right): the host name, host stratum, time offset between that host and the local host (as measured by XNTPTRACE; this is why it is not always zero for localhost), host synchronization distance, and (only for stratum-1 servers) the reference clock ID. All times are given in seconds.

Note! The stratum is the server hop count to the primary source, while the synchronization distance is the estimated error relative to the primary source. The NTP server must be synchronized to a peer.

Format

xntptrace [ -dnv ] [-o version#] [ -r retries ] [ -t timeout ] [ server ]

Command Line Options

-n

Turns off the printing of hostnames; instead, host IP addresses are given. This may be useful if a nameserver 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.