10. Network Time Protocol (NTP)

Introduction

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

TCPware’s NTP also includes two standard query programs, NTPQ and NTPDC, the utility NTPTRACE, and the NTPDATE program.

TCPware’s NTP implementation is based on Network Time Protocol Version 4.2.

Overview of NTP

The standard timescale used by most nations of the world is Coordinated Universal Time (UTC), which is based on the Earth's rotation about its axis, and the Gregorian Calendar, which is based on the Earth's rotation about the Sun. UTC time is disseminated by various means, including radio and satellite navigation systems, telephone modems and portable clocks. For reasons of cost and convenience, it is not possible to equip every computer with a method of receiving these time signals directly. However, it is possible to equip some number of computers acting as primary time servers to synchronize a much larger number of secondary servers and clients connected by a common network. In order to do this, a distributed network clock synchronization protocol is required which can transmit an accurate reading to one or more clients and adjust each client clock as required. This is what the Network Time Protocol is for.

The synchronization protocol determines the time offset of the server clock relative to the client clock. On request, the server sends a message including the time the request arrived and the time the response was returned. The client included the time it sent the request in the request message and records the time the response arrived back from the server as well. With these four values, or timestamps, the client can determine the server-client propagation delay (by assuming that this is half the round-trip time) and subtract this from the time difference between client and server time settings to determine its clock offset relative to the server. In general, this is a useful approximation; however, in the Internet of today, network paths and the associated delays can differ significantly due to the individual service providers, and this can contribute to error in determining offset. A stable, symmetrical (in terms of propagation delay) and reliable connection to the time server is important in minimizing this type of error.

NTP attempts to compensate for the problem of network instability by allowing the use of several servers as time sources and determining which of them is most reliable through statistical means that compare them to each other. All sources are assumed to have correct times, but those that differ markedly from the group are eventually ignored as having unreliable connections or being otherwise poor sources of correct time information. This tends to limit malicious activities as well, where a server that reports false times is inserted in a network, as well as bad time servers that result from hardware failure that can have much the same effect.

Clock errors can be due to other causes than variations in network delay. Other causes include latencies in computer hardware and software (jitter), as well as clock oscillator instability (wander). Despite these sources of error, NTP can, over many updates, discipline a clock to stay remarkably close to the actual time, even when a time server is not available for some period.

Programs and Files

There are several programs and files that make up NTP in TCPware. These are described in more detail later in this chapter.

Program Files

The following programs make up the NTP implementation in TCPware:

NTPD	The NTP server process used to maintain the system clock and to pass time information to lower stratum clients and servers. While this program runs as a server process, it also functions as a client in requesting time data from other servers on the network.
NTPDATE	An interactive “one shot” time setting utility. It is useful for setting the initial time on a system, perhaps at boot time, to minimize the correction necessary with NTPD. If NTPD is not desired for some reason, NTPDATE used in a recurring batch job can be used to maintain a system’s clock accurately.
NTPDC	NTPDC is used to query the NTPD server about its current state and to request changes in that state. Extensive state and statistics information is available through the NTPDC interface. In addition, nearly all the configuration options which can be specified at startup using NTPD's configuration file may also be specified at run time using NTPDC.
NTPQ	The NTPQ utility program is used to query NTP servers about current state and to request changes in that state. Requests to read and write arbitrary variables can be assembled, with raw and pretty-printed output options being available. NTPQ can also obtain and print a list of peers in a common format by sending multiple queries to the server. NTPQ and NTPDC perform similar functions, but use different protocols to communicate with NTPD.
NTPTRACE	NTPTRACE determines where a given NTPD server gets its time, and follows the chain of NTP servers back to their master time source.

Configuration Files

NTP uses the following configuration files:

NTP.CONF	TCPWARE:NTP.CONF is used to specify servers from which time information is requested as well as many other aspects of NTPD behavior. See the description of NTPD for a list of options and their definitions. NTP.CONF is read only at NTPD startup, so if you make changes you will need to restart NTPD.
NTP.KEYS	TCPWARE:NTP.KEYS is used to define security information used in authorization operations. (The keys used by the NTPQ and NTPDC programs are checked against passwords requested by the programs and entered by hand.)
TIMEZONES.DAT	A default set of timezone rules is compiled into NTP. You can use the TCPWARE SET/TIMEZONE command in conjunction with this file to add other time zone rules. See the Time Zone section for more information about time zones and the use of this file.

Other Files

NTP uses the following files:

NTPD.LOG	The NTPD server outputs progress and error information to the TCPWARE:NTPD.LOG file. (See Troubleshooting Tips.)
NTP.DRIFT	The TCPWARE:NTP.DRIFT file consists of data maintained by NTPD and used to speed up clock frequency adjustments when NTPD is restarted. You should not modify this file.

Configuration

NTP Network Design

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 sources and available transmission paths to those sources. This is a fine point which is worth understanding. A group of NTP-synchronized clocks may be close to each other in time, but this is not a consequence of the clocks in the group having synchronized to each other, but rather because each clock has synchronized closely to UTC via the best source it has access to.

The most important factor in providing accurate, reliable time is the selection of modes and servers to be used in the configuration file. An NTP network should consist of a multiply redundant hierarchy of servers and clients, with each level in the hierarchy identified by stratum number. Primary servers operate at stratum one and provide synchronization to secondary servers operating at stratum two and so on to higher strata. In this hierarchy, clients are simply servers that have no dependents.

Determine which list of peers/servers you want to include in the configuration file. Include at least one (but preferably two) peer or server hosts that you are assured:

· Are running NTP.

· Provide accurate time.

· Synchronize to Internet Time Servers (if they are not themselves ITSs).

Two hosts provide reliability in case one goes down. You do not need to identify what stratum each host is. NTP determines this through the reference information it sends in its data exchanges.

NTP data is exchanged periodically between hosts as encapsulated in UDP datagrams, and adjustments are made based on an NTP algorithm. The frequency of exchange is related to the server’s experience of time corrections. The more accurate the local clock becomes over time and after many adjustments, the less often the NTP server checks the need for corrections. 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.

Primary servers are servers with reliable time sources, such as GPS receivers or atomic clocks, and can be found on the public internet, or set up within an intranet. Stratum numbers equate to the number of intermediate servers (or hops) between a given host and the Stratum 1 server it is ultimately referencing. Stratum numbers are not assigned statically, but change as server connections change. NTP servers can be (and often are) other types of systems running NTP, not just OpenVMS systems.

The stratum method allows for backup timekeeping in case a node or connection goes down, and stratum numbers may change as a consequence. In diagram A below, 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. Diagram B below shows the same network with one of the connections broken — note that the stratum for the affected peer increases from 2 to 3.

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

Under some circumstances it can be disruptive to step the clock, such as when running database software that journals transactions. Such software can become very confused when a transaction is completed prior to the time at which it began, such as can happen when a clock is stepped backwards during a transaction’s lifetime. In such cases the slewalways configuration option can be used to turn off stepping of the clock and force all adjustments to be made by slewing. For large time changes, such as DST changeovers, the adjustment can take a long time (several hours) to complete, and during this time the system’s time will not be correct. For this reason it is not wise to allow a system set for slewalways to act as a server to another system.

In determining your NTP network design, keep in mind the way that the NTP protocol works, and how NTPD will determine the correct time. There should be several time servers in the configuration for each node, with good, reliable, and non-congested paths between them. Nodes that will act only as clients can use the slewalways option, but nodes used as time sources by other nodes should generally allow stepping of the time so that inaccurate times are not reported for extended periods at Daylight Savings Time (DST) changeovers. See the NTP.CONF section of this chapter for more information on the slewalways option and the Timezone section for more information on DST handling.

Authentication

NTP implements a general-purpose address- and mask-based restriction list (see the restrict configuration option). While this is not adequate to prevent hacking attacks, it can be useful to lock out a malfunctioning server that is disrupting normal operations. See the Access Control Commands section for more information.

Finding Servers

In many large organizations there is an administrator for the organization’s networks which handles management of various network services. This person or department can usually provide information on local NTP servers, and often suggest configurations that are known to work.

There are also several publicly available time servers on the internet. A list of such servers can be accessed via the web at http://www.eecis.udel.edu/~ntp These data are updated on a regular basis using information provided voluntarily by various site administrators.

NTP.CONF

The NTP.CONF file is used to specify the initial configuration of the NTPD server. It contains information about servers and peers, modes of operation, non-default file names, and other configuration data. See the table for a list of available options, and a brief description of what each does.

peer

peer [ address ] [ version 4 ] [key 0] [minpoll 6] [maxpoll 10]

Specifies that the server is to operate in symmetric active mode with the specified 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.

The address can be a domain name or an IP address in dotted quad notation

The key specifies that 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 specifies the protocol version number to be used for outgoing NTP packets. Versions 1, 2, 3 and 4 are the choices, with version 4 the default.

server

server [ address ] [ version 4 ] [key 0] [minpoll 6] [maxpoll 10]

Specifies that the local server is to operate in 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.

The address can be a domain name or an IP address in dotted quad notation

version specifies the protocol version number to be used for outgoing NTP packets. Versions 1, 2, 3 and 4 are the choices, with version 4 the default.

broadcast

broadcast [ address ] [ version 4 ] [ key 0 ] [ ttl 1 ]

Specifies broadcast mode, where the local server sends periodic broadcast messages to a client population at the broadcast/multicast address specified. This specification applies only to the local server operating as a sender. For operation as a broadcast client, see the broadcastclient option that follows. In this mode address is usually the broadcast address on (one of) the local networks.

version specifies the protocol version number to be used for outgoing NTP packets. Versions 1, 2, 3 and 4 are the choices, with version 4 the default.

ttl specifies the number of routers to pass through before the packet is discarded. The default is 127 routers.

broadcastclient

This command directs the local server to listen for broadcast messages at the broadcast address of the local network. 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.

multicastclient

multicastclient [ address ]

Specifies that this host is a multicast client for multicasts to the specified multicast address.

manycastclient

manycastclient [address] [version 4] [key 0] [minpoll 6] [maxpoll 10]

Specify that this host is a manycast client and provide relevant settings.

manycastserver

manycastserver [ address ]

Specify that this host is a manycast server for the given address.

broadcastdelay

broadcastdelay 0.004

The broadcast and multicast modes require a special calibration to determine the network delay between the local and remote servers. Ordinarily, this is done automatically by the initial protocol exchanges between the client and server. In some cases, the calibration procedure may fail due to network or server access controls, for example. This command specifies the default delay to be used under these circumstances. Typically (for Ethernet), a number between 0.003 and 0.007 seconds is appropriate. The default when this command is not used is 0.004 seconds.

restrict

restrict [ address ] [ mask 255.255.255.0 ] ignore|noserve|notrust|noquery

Restrict access from and to the specified address for the specified types of access.

The 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 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.

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 generated by NTPQ and NTPDC) from the source. Time service is not affected.

noserve - Ignores NTP packets whose mode is other than 6 or 7. In effect, time service is denied, though queries may still be permitted.

notrust - Treats these hosts normally in other respects, but never uses them as synchronization sources.

driftfile

driftfile file_name

Specify the name of the drift file. The default is MULTINET:NTP.DRIFT if this option is not used.

The drift file is used to record the frequency offset of the local clock oscillator. If the file exists, it is read at startup in order to set the initial frequency offset and then updated once per hour with the current frequency offset computed by the daemon. If the file does not exist or this command is not given, the initial frequency offset is assumed zero. In this case, it may take some hours for the frequency to stabilize and the residual timing errors to subside.

local-master

local-master stratum

Indicates that the system is to act as an authoritative time source for other systems at a stratum level lower than the specified stratum.

keys

keys file_name

Specify the name of the keys file. The default is MULTINET:NTP.KEYS if this option is not used.

statsdir

statsdir 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

filegen [ file filename ] [ type typename ] [ enable | disable ]

Configures 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.

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.

filename - This string is directly concatenated to the directory MULTINET: or the directory prefix specified using the statsdir option. The suffix for this filename is generated according to the type of a fileset.

typename - A file generation set is characterized 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.

Information is only written to a file generation by specifying enable; output is prevented by specifying disable.

publickey

publickey file_name

Specify the public keys file location.

privatekey

privatekey file_name

Specify the private key file location.

clientlimit

clientlimit [ n ]

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

clientperiod

clientperiod [ 3600 ]

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.

trustedkey

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

requestkey [ key]

Specifies the key identifier to use with the NTPDC program, which uses a proprietary protocol specific to this distribution of NTPD. 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, NTPDC requests are ignored.

controlkey

controlkey [ key ]

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

setvar

setvar [ value ]

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 (ntpq 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.

logfile

logfile file_name

Specify the logfile name. The default is MULTINET:NTPD.LOG if this option is not specified.

logconfig

logconfig [+|-|=] [{sync|sys|peer|clock}{{,all}{info|statistics|events|status}}]...

Specify logging options.

enable

Enable various options.

auth - Enables the server to synchronize with unconfigured peers only if the peer was correctly authenticated using a trusted key and key identifier. The default for this setting is disable.

bclient - When enabled, this is identical to the broadcastclient command. The default for this flag is disable.

ntp - Enables the server to adjust 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 in case the local clock is controlled by some other device or protocol and NTP is used only to provide synchronization to other clients. The default for this flag is enable.

kernel - this setting is not used in the MultiNet implementation.

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

stats - Enables the statistics facility. For further information, see Monitoring Commands. The default for this flag is enable.

calibrate - this setting is not used in the MultiNet implementation.

disable

Disable various options. See the enable entry for details.

slewalways

Slewalways

Specify that the clock time is always to be slewed, never stepped.

NTPD normally steps the clock when there is a relatively large time error to adjust. The slewalways command directs the local NTP server to always slew the clock, regardless of how large the required correction is. 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, NTPD slews the clock over a period of about 6 hours.

panic

panic max_adjust_time

Set the maximum time change that will be allowed. If non-zero, this value should always be at least 4000 seconds to allow for DST time changes even on systems with large time errors.

If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted.

debug

debug [level]

Set the debug logging severity level.

set_vms_logicals

Causes the NTP server to also adjust the value of the VMS logicals SYS$TIMEZONE_DIFFERENTIAL, SYS$TIMEZONE_DAYLIGHT_SAVING and SYS$TIMEZONE_NAME when it changes the MULTINET_TIMEZONE logical at DST start or end. The following files will also be updated: DTSS$TIMEZONE_DIFFERENTIAL and SYS$TIMEZONE.DAT

NTP does NOT set SYS$TIMEZONE_RULE, which generally does not change. The format of SYS$TIMEZONE_RULE is specified in SYS$MANAGER:UTC$TIME_SETUP.COM.

call_dst_proc

Causes the NTP server to spawn a subprocess to execute the MULTINET:NTPD_DST_PROC.COM procedure, if such a procedure file exists with the proper protections, when changing into or out of DST, or when first starting up. See the Using the call_dst_procoption below for more information.

set_clock_daily

When this is included in NTP.CONF, then NTPD will only make one call a day (instead of once an hour) to the routine that sets the TOY clock to ensure that the value is preserved. This reduces the number of entries in the Integrity system event logs. NTPD may set the clock more often than daily, but it will be done only to correct any drift that is detected. In our tests on a RX2600 this happened approximately every 6 hours.

Access Control Commands

NTP implements a general-purpose address- and mask-based restriction list (see the restrict config option). 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 NTP authentication facility. Source address-based restrictions are easily circumvented by a determined hacker.

Authentication Using a Keys File

The NTP standard specifies an extension which provides cryptographic authentication of received NTP packets. This is implemented in NTPD 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 TCPWARE: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 NTPQ utility program, and the third for the NTPDC utility program.

Key File Format

For MD5, keys are 64 bits (8 bytes), read from the TCPWARE: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 scheme must be identical between a set of peers sharing the same key number.

Note: The keys used by the NTPQ and NTPDC programs are checked against passwords requested by the programs and entered by hand.

Using the call_dst_proc option

When NTPD is started, and whenever the local time zone shifts between daylight savings DST and standard (STD) time, if the local zone rule specifies such behavior, the NTPD server will check the TCPWARE_TIMEZONE logical, and set it if required. The setting will only be between the DST name and the STD name for the zone, so the configuration described above is still necessary, but if your system was down during a DST shift, this can correct the logical name to match the current system clock time and the applicable zone rule when NTPD is started. If your NTP.CONF file specifies the set_vms_logicals option, the SYS$TIMEZONE_DIFFERENTIAL, SYS$TIMEZONE_DAYLIGHT_SAVING and SYS$TIMEZONE_NAME logicals will be updated as well.

Since there are many systems with other time-related logical names, or other items that may need updating or adjusting based on a DST change, the call_dst_proc option has been provided. If this option is used in NTP.CONF, the NTPD server will look for a file called TCPWARE:NTPD_DST_PROC.COM any time it checks on the TCPWARE_TIMEZONE logical (at startup and at a DST shift). If this file exists, and has the proper protections (no WORLD write or execute access, and owned by SYSTEM ([1,4])) a sub-process will be spawned to execute it. This procedure can contain any commands needed, but care should be exercised in constructing this file, as it will be executing with the same privileges as the NTPD process. A “placeholder” procedure is included with TCPware contents are all comments and will do nothing as shipped.

The invocation of the TCPWARE:NTPD_DST_PROC.COM procedure will be equivalent to this:

@TCPWARE:NTPD_DST_PROC.COM p1 p2 p3 p4 p5

Where:

· p1 = Current time zone name - string (e.g. "EST" or "EDT")

· p2 = Time zone offset in seconds - integer (e.g. "-18000" or "-14400")

· p3 = DST in effect? - boolean ("Y", "N")

· p4 = In Twilight Zone? - boolean ("Y", "N")

· p5 = Startup or DST change? - string ("START" or "DST")

P1, the Current Time Zone Name, is a string specifying the current name of the local time zone. For North American Eastern Standard Time, this will be “EST” in the winter, and “EDT” in the summer, when DST is active. For time zones that don’t do DST, it will always be the zone name.

P2, the Time Zone Offset, is a signed integer specifying the offset, in seconds, from UTC for the local zone, at the current time. For North American Eastern Standard Time this is “-18000” (-5 hours), for the same zone with DST in effect it is “-14400” (-4 hours).

P3, the DST flag. This will be “Y” if DST is currently in effect for the zone, and “N” if it isn’t, or if the zone doesn’t do DST.

P4, the Twilight Zone flag. When a zone exits from DST, it sets its time back an hour. This means that for that hour, the time *appears* to be a DST time by the local DST rules, but isn’t really, since DST has already ended. That hour is called the “twilight zone” by TCPware NTP. If the current time is in that period, the P4 parameter will be “Y”, otherwise it will be “N”.

P5, the startup/DST flag. This tells the procedure whether it is being called as a part of NTPD’s startup processing, or as part of a DST change.

These parameters are provided so that the procedure can take different action under different conditions. They may all be ignored if that is appropriate. The NTPD server doesn’t depend on any particular behavior, so long as the TCPWARE_TIMEZONE logical is left alone and the system clock is not altered. The final completion status of the called procedure will be logged by the NTPD server, along with the PID of the spawned sub-process.

NTP Utilities

There are several utility programs included with NTP. These allow setting the system clock from a time server, querying and controlling NTP servers on the local system or on remote hosts, and tracing the chain of time servers back to the top stratum server being used to set the local time.

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 NTP 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 NTPDATE 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 NTP daemon, NTPD. It is also possible to run NTPDATE from a batch job. However, it is important to note that NTPDATE with contrived batch jobs is no substitute for the NTP daemon, which uses sophisticated algorithms to maximize accuracy and reliability while minimizing resource use. Finally, since NTPDATE does not discipline the host clock frequency as does NTPD, the accuracy using NTPDATE is limited.

The NTPDATE 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 second, 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 NTPDATE is run by a batch job every hour or two.

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

Format

ntpdate [ -bBdoqsuv ] [ -a key ] [ -e authdelay ] [ -k keyfile ] [ -o version ] [ -p samples ] [-t timeout ] 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 large, it can sometimes 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.

-d

Enable the debugging mode, in which ntpdate will go through all the steps, but not adjust the local clock. Information useful for general debugging will also be printed.

-e authdelay

Specify the processing delay to perform an authentication function as the value authdelay, in seconds and fraction. This number is usually small enough to be negligible for most purposes, though specifying a value may improve timekeeping on very slow CPU's.

-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 NTPD configuration.

-o version

Specifies the NTP version for outgoing packets as the integer version, which can be 1, 2, 3 or 4. The default is 4. This allows NTPDATE 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.

-q

Query only - don't set the clock.

-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 NTPDATE 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.

-v

Be verbose. This option will cause ntpdate's version identification string to be logged.

NTPTRACE

The NTPTRACE utility determines where a given NTP server gets its time, 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 NTPTRACE:

$ ntptrace
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 NTPTRACE; 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

ntptrace [-vdn] [-r retries] [-t timeout] [server]

Command Line Options

-d

Turns on some debugging output.

-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.

NTPDC

The NTPDC utility is used to query the NTPD server 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 NTPDC interface. In addition, nearly all the configuration options that can be specified at startup using NTPD’s configuration file may also be specified at run-time using NTPDC.

The NTPDC utility uses NTP mode 7 packets to communicate with the NTP 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. NTPDC makes no attempt to retransmit requests, and times out requests if the remote host is not heard from within a suitable timeout time.

NTPDC’s operation is specific to the NTPD implementation and can be expected to work only with this, and possibly some previous versions, of the daemon. Requests from a remote NTPDC 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.

Command Line Format

ntpdc [-ilnps] [-c command] [host] [...]

Command Line Arguments

(If command line arguments are omitted, NTPDC 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.

-i

Force ntpdc to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.

-l

Obtain a list of peers which are known to the server(s). This switch is equivalent to -c listpeers.

-n

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

-p

Print a list of the peers known to the server as well as a summary of their state. This is equivalent to -c peers.

-s

Print a list of the peers known to the server as well as a summary of their state, but in a slightly different format than the -p switch. This is equivalent to -c dmpeers.

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.

Interactive 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.

hostnames [ yes | no ]

If yes is specified, host names are printed in information displays. If no is specified, numeric addresses are printed instead. The default is yes, unless modified using the command line -n switch.

keyid [ keyid ]

Allows a key number to be used by NTPDC to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose.

quit

Exits NTPDC.

passwd

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.

timeout [milliseconds]

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

Note: Since NTPDC retries each query once after a timeout, the total waiting time for a timeout is twice the timeout value set.

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).

The character in the left margin indicates the mode this peer entry is operating in as per the table:

+	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.

dmpeers

A slightly different peer summary list. Identical to the output of the peers command, except for the character in the leftmost column. Characters only appear beside peers which were included in the final stage of the clock selection algorithm. Characters indicate server validity according to the following table:

.	peer was cast off in the falseticker detection
+	peer made it through falseticker detection
*	peer the server is currently synchronizing with

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. Understanding this information will require a detailed understanding of the inner workings of the NTP protocol, which is also available in the RFCs that specify the protocol.

pstats peer-address [...]

Shows per-peer statistic counters associated with the specified peer(s).

loopinfo [ oneline | multiline ]

Prints the values of selected loop filter variables. The loop filter is the part of NTP which deals with adjusting the local system clock.

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 NTPD section 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 server, something might be wrong with the local clock.

The broadcastdelay shows the default broadcast delay, as set by the broadcastdelay configuration command. The authdelay shows the default authentication delay, as set by the authdelay configuration command.

sysstats

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 NTPDC. This can be done using NTPDC’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 non-zero 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, 3 or 4, and defaults to 4. 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 NTP. 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 NTPD.

restrict address mask flag [ flag ]

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

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 NTPD.

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.

NTPQ

The NTPQ utility is used to query NTP 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. NTPQ 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 NTP 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. NTPQ makes one attempt to retransmit requests, and times out requests if the remote host is not heard from within a suitable timeout time.

Command Line Format

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

If command line arguments are omitted, NTPQ runs in interactive mode.

-c

-i

Force NTPQ to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.

-n

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

-p

Print a list of the peers known to the server as well as a summary of their state. This is equivalent to the peers interactive command.

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.

Interactive Commands

Internal Commands

Internal commands are executed entirely within the NTPQ program itself and do not result in NTP mode 6 requests being sent to a server.

? [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 for that command.

addvars variable_name [ = value ] [ ... ]
rmvars variable_name [ ... ]
clearvars

The data carried by NTP mode 6 messages consists of a list of items of the form variable_name = value, where the = value is ignored, and can be omitted, in requests to the server to read variables. NTPQ maintains an internal list in which data to be included in control messages can be assembled, and sent using the readlist and writelist commands described below. The addvars command allows variables and their optional values to be added to the list. If more than one variable is to be added, the list should be comma-separated and not contain white space. The rmvars command can be used to remove individual variables from the list, while the clearlist command removes all variables from the list.

authenticate yes | no

Normally NTPQ does not authenticate requests unless they are write requests. The command authenticate yes causes NTPQ to send authentication with all requests it makes. Authenticated requests cause some servers to handle requests slightly differently.

cooked

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

debug more | less | off

Turns internal query program debugging on and off.

delay milliseconds

Specify a time interval to be added to timestamps included in requests which require authentication. This is used to enable (unreliable) server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. The server does not now require timestamps in authenticated requests, so this command may be obsolete.

host [ hostname ]

Sets the host to which future queries are sent. Hostname may be either a hostname or a numeric address.

hostnames [ yes | no ]

If yes is specified, hostnames are printed in information displays. If no, numeric addresses are printed instead. The default is yes, unless modified using the command line -n switch.

keyid keyid

This command allows the specification of a key number to be used to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose.

ntpversion [ 1 | 2 | 3 | 4 ]

Sets the NTP version number that NTPQ claims in packets. Default is 4. Mode 6 control messages (and modes) didn't exist in NTP version 1.

quit

Exits NTPQ.

passwd

This command prompts you to type in a password (which will not be echoed) which will be used to authenticate configuration requests. The password must correspond to the key configured for use by the NTP server for this purpose if such requests are to be successful.

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. Since NTPQ 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.

Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to be printed in some format. Most commands currently implemented send a single message and expect a single response. The current exceptions are the peers command, which will send a preprogrammed series of messages to obtain the data it needs, and the mreadlist and mreadvar commands, which will iterate over a range of associations.

associations

Obtains and prints a list of association identifiers and peer status for in-spec peers of the server being queried. The list is printed in columns. The first of these is an index numbering the associations from 1 for internal use, the second is the actual association identifier returned by the server, and the third is the status word for the peer, 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 [ assocID ] [ variable_name [ = value [ ... ]] [ ... ]
cv [ assocID ] [ variable_name [ = value [ ... ] ] [ ... ]

Requests that a list of the server's clock variables be sent. Servers which have a radio clock or other external synchronization will respond positively to this. If the association identifier is omitted or zero the request is for the variables of the system clock and will generally get a positive response from all servers with a clock. If the server treats clocks as pseudo-peers, and hence can possibly have more than one clock connected at once, referencing the appropriate peer association ID will show the variables of a particular clock. Omitting the variable list will cause the server to return a default variable display.

lassocations

Obtains and prints a list of association identifiers and peer statuses for all associations for which the server is maintaining state. This command differs from the associations command only for servers which retain state for out-of-spec client associations (i.e., fuzzballs). Such associations are normally omitted from the display when the associations command is used, but are included in the output of lassociations.

lpassociations

Print data for all associations, including out-of-spec client associations, from the internally cached list of associations. This command differs from passociations only when dealing with fuzzballs.

lpeers

Like the peers command, except a summary of all associations for which the server is maintaining state is printed. This can produce a much longer list of peers from fuzzball servers.

mreadlist assocID assocID
mrl assocID assocID

Like the readlist command, except the query is done for each of a range of (non-zero) association IDs. This range is determined from the association list cached by the most recent associations command.

mreadvar assocID assocID [ variable_name [ = value [ ... ]
mrv assocID assocID [ variable_name [ = value [ ... ]

Like the readvar command, except the query is done for each of a range of (non-zero) association IDs. This range is determined from the association list cached by the most recent associations command.

opeers

An old form of the peers command with the reference ID replaced by the local interface address.

passociations

Displays association data concerning in-spec peers from the internally cached list of associations. This command performs identically to the associations except that it displays the internally stored data rather than making a new query.

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:

character	rv cmd	Description
<space>	reject	The peer is discarded as unreachable, synchronized to this server (synch loop) or outrageous synchronization distance.
x	falsetick	The peer is discarded by the intersection algorithm as a falseticker.
.	excess	The peer is discarded as not among the first ten peers sorted by synchronization distance and so is probably a poor candidate.
-	outlyer	Discarded by the clustering algorithm
+	candidat	The peer is a survivor and a candidate for the combining algorithm.
#	selected	The peer is a survivor, but not among the first six peers sorted by synchronization distance. If the assocation is ephemeral, it may be demobilized to conserve resources.
*	peer	The peer has been declared the system peer and lends its variables to the system variables.
o	peer	The peer has been declared the system peer and lends its variables to thesystem variables. However, 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 three forms. It may be a hostname, an IP address, or a reference clock implementation name with its parameter. 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. The status word from the header is displayed preceding the variables, both in hexidecimal and in English.

readlist [ assocID ]
rl [ assocID ]

Requests that the values of the variables in the internal variable list be returned by the server. If the association ID is omitted or is 0 the variables are assumed to be system variables. Otherwise they are treated as peer variables. If the internal variable list is empty a request is sent without data, which should induce the remote server to return a default display.

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.

writevar assocID variable_name [ = value [ ...]

Like the readvar request, except the specified variables are written instead of read.

writelist [ assocID ]

Like the readlist request, except the internal list variables are written instead of read.

NTP Management

Implementing NTP

To implement NTP:

1. Determine the hosts (peers and servers) with which the local system should negotiate for synchronization.

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

3. Start the NTPD daemon running.

4. Use one of the query programs to verify proper operation.

Modifying the NTP Configuration File

To configure only NTP, you can enter @TCPWARE:CNFNET NTP. Then add entries to the TCPWARE:NTP.CONF peer configuration file. The commands you add to the file have the syntax and meaning described in the previous section on the NTP.CONF file.

Monitoring

NTP includes a comprehensive monitoring facility suitable for continuous, long term recording of server and client timekeeping performance. (See the statistics configuration option for a listing of each type of statistic currently supported.)

Troubleshooting Tips

Here are some troubleshooting tips:

· Make sure the entries in the NTP configuration file TCPWARE: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. The machine serving time must be connected either to lower stratum machines or to some reference time source.

· Make sure that the logical TCPWARE_TIMEZONE is properly defined to reflect the time zone (and daylight savings). If the logical is undefined or incorrect, NTP is likely to abort. TCPWARE_TIMEZONE should be set by configuring TCPware with the configuration procedure TCPWARE:CNFNET.COM.

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

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

· The following messages are generated by the NTP server. They go to both OPCOM and the TCPWARE:NTPSERVER.LOG file. This log file is the best source of information for troubleshooting 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:

o Configuration messages

o Peer contact messages

o Synchronization messages

o Unexpected error condition messages

Access error messages help by entering:

$ HELP TCPWARE MESSAGES

Troubleshooting Using NTPQ

The NTPQ 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 */

Configuration Example

The diagram below 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.

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.

The below example 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.

; NTP Configuration on 192.168.67.1
master-clock 1

; NTP 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

; NTP 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

; NTP 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
.
.
.