home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 35 Internet
/
35-Internet.zip
/
os2ntp12.zip
/
os2_ntpd.man
< prev
next >
Wrap
Text File
|
1998-06-21
|
28KB
|
487 lines
User's Guide to OS2_NTPD,
Network Time Protocol Client for OS/2 Warp
Release 1.2, June 21, 1996
by
Bruce M. Penrod (bpenrod@nbn.com)
I. INTRODUCTION
OS2_NTPD is a 32-bit, multi-threaded, text mode, NTP client application that
runs in a Presentation Manager text window. It requires either OS/2 2.1 with
TCP/IP version 2.0 or OS/2 version 3.0 or 4.0 (aka WARP or WARP Connect) to
operate. It may reside in either an HPFS or FAT partition. Three files must be
present in the same directory:
1) os2_ntpd.exe (the main program)
2) portio.dll (a dynamic link library which gives os2_ntpd.exe access
to the I/O ports and thereby the real time clock chip.
It must reside in a directory included in the LIBPATH=
statement of the config.sys or in the directory from
which os2_ntpd.exe is executed.)
3) cfg_data (data file containing the list of NTP servers to poll
and the initial polling interval--optional if provided
from command line in single server mode)
In addition, tcp32dll.dll and so32dll.dll must be present on the system in a
directory which is included in the LIBPATH= statement in the config.sys.
After OS2_NTPD has been executed the first time, these additional files will be
created in the same directory:
1) rtc_type (data file containing the type of real time clock chip
present on the system board--there are two different
types, unfortunately, indicated by a value of either 0
or 500 in this file)
2) drift (data file containing the NTP timestamp rounded to
whole seconds of the last correction that was made to
the real time clock followed by the fractional
frequency offset of the real time clock timebase,
positive means that the system clock is fast. It may
take several hours for this file to appear the first
time)
3) suspects (when debugging is enabled, data file containing server
reply packets which differ from the client ensemble
clock by more than 250 ms. This file may grow without
bound, so it should be checked and deleted from time to
time. The format of these packets is identical to that
which is displayed on the user interface screen)
In addition, if logfile is turned on, then a log file with name equal to the
NTP seconds (seconds since Jan 1, 1900) in hexadecimal at the time the logfile
was first opened and extension equal to "log" is created, for example a
typical logfile name might be:
b5afc01a.log
This logfile contains a list of the NTP servers which were present in the
cfg_data file when the program was first executed, followed by an NTP timestamp
column which is followed by three columns for each server of statistics on the
time received from that server. These statistics are the current raw
measurement of that (server - client), the mean of these raw measurements taken
over approximately twenty samples, and the standard deviation of these raw
measurements.
After the statistics for each of the servers come columns which contain the
ensemble statistics. The first ensemble statistic is the ensemble, or weighted
average of all of the (server - client) raw measurements. This is followed by
the standard deviation of the ensemble. Next is the phase locked loop filter
output value, followed by the fractional frequency offset of the local clock
timebase, followed finally by the actual clock correction in seconds applied to
the system clock.
II. INSTALLATION
*********************************IMPORTANT************************************
If you are upgrading from version 1.0, you MUST replace both the os2_ntpd.exe
and the portio.dll files. The version of portio.dll included with version 1.0
IS NOT COMPATIBLE with version 1.2.
******************************************************************************
Installation is simple, just create a directory and unzip the distribution file,
os2ntp12.zip into it. In addition, check the system config.sys file on the
OS/2 boot partition and make sure that the line:
IOPL=YES
is present in it. If it is not, or is set equal to NO, change it. OS2_NTPD
MUST HAVE ACCESS to I/O ports in order to read and set the system real
time clock chip. As an alternative to providing broad IOPL access, specific
access to certain executables is possible, for example:
IOPL=os2_ntpd.exe
is also OK.
Since NTP is based on UTC time, it will be necessary to set the environment
variable TZ so that the local offset to UTC may be maintained when OS2_NTPD is
operating on the system clock. A statement like this must appear somewhere in
your config.sys:
SET TZ=PST+8PDT
This example is appropriate for users on the west coast of the USA who
operate with Pacific Standard Time (PST) or Pacific Daylight Time (PDT) and
are 8 hours behind UTC when PST is in effect. If daylight time is not used,
leave off the last three characters:
SET TZ=PST+8
To set TZ for more complicated situations, use the following format:
┌──────────────────────────────────────────────────────────────────────────────┐
│ │
│ >>──SET──TZ──=──SSS──┬──────────────────────────────┬──────────────────────> │
│ └─┬───┬──h──┬────────────────┬─┘ │
│ ├─+─┤ └─:──m──┬──────┬─┘ │
│ └─┴─┘ └─:──s─┘ │
│ │
│ >──┬─────────────────────────────────────────┬────────────────────────────>< │
│ └─DDD──┬────────────────────────────────┬─┘ │
│ └─,sm,sw,sd,st,em,ew,ed,et,shift─┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
The values for the TZ variable are defined below. The default values given are
for the built-in "C" locale defined by the ANSI C standard.
┌──────────────────────────────────────────────────────────────────────────────┐
│ Table 1. TZ Environment Variable Parameters │
├──────────────┬─────────────────────────────────────────────┬─────────────────┤
│ VARIABLE │ DESCRIPTION │ DEFAULT VALUE │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ SSS │ Standard-timezone identifier. It must be │ EST │
│ │ three characters, must begin with a letter, │ │
│ │ and can contain spaces. │ │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ h, m, s │ The variable h specifies the difference (in │ 5 │
│ │ hours) between the standard time zone and │ │
│ │ coordinated universal time (CUT), formerly │ │
│ │ Greenwich mean time (GMT). You can │ │
│ │ optionally use m to specify minutes after │ │
│ │ the hour, and s to specify seconds after │ │
│ │ the minute. A positive number denotes time │ │
│ │ zones west of the Greenwich meridian; a │ │
│ │ negative number denotes time zones east of │ │
│ │ the Greenwich meridian. The number must be │ │
│ │ an integer value. │ │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ DDD │ Daylight saving time (DST) zone identifier. │ EDT │
│ │ It must be three characters, must begin │ │
│ │ with a letter, and can contain spaces. │ │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ sm │ Starting month (1 to 12) of DST. │ 4 │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ sw │ Starting week (-4 to 4) of DST. Use nega- │ 1 │
│ │ tive numbers to count back from the last │ │
│ │ week of the month (-1) and positive numbers │ │
│ │ to count from the first week (1). │ │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ sd │ Starting day of DST. │ 0 │
│ │ 0 to 6 if sw != 0 │ │
│ │ 1 to 31 if sw = 0 │ │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ st │ Starting time (in seconds) of DST. │ 3600 │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ em │ Ending month (1 to 12) of DST. │ 10 │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ ew │ Ending week (-4 to 4) of DST. Use negative │ -1 │
│ │ numbers to count back from the last week of │ │
│ │ the month (-1) and positive numbers to │ │
│ │ count from the first week (1). │ │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ ed │ Ending day of DST. │ 0 │
│ │ 0 to 6 if ew != 0 │ │
│ │ 1 to 31 if ew = 0 │ │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ et │ Ending time of DST (in seconds). │ 7200 │
├──────────────┼─────────────────────────────────────────────┼─────────────────┤
│ shift │ Amount of time change (in seconds). │ 3600 │
└──────────────┴─────────────────────────────────────────────┴─────────────────┘
For example:
SET TZ=CST6CDT
sets the standard time zone to CST, the daylight saving time zone to CDT, and
sets a difference of 6 hours between CST and CUT. It does not set any values for
the start and end date of daylight saving time or the time shifted.
When TZ is not present, the default is EST5EDT, the "C" locale value. When only
the standard time zone is specified, the default value of n (difference in hours
from GMT) is 0 instead of 5.
If you give values for any of sm, sw, sd, st, em, ew, ed, et, or shift, you must
give values for all of them. Otherwise the entire statement is considered not
valid, and the time zone information is not changed.
About the Real Time Clock
For system timekeeping and task scheduling, OS/2 uses the Motorola MC146818 RTC
chip which IBM originally designed into the AT machines. Prior to FixPak 26 for
Warp v3 and FixPak 1 for Warp v4, OS/2 set the chip up to generate an interrupt
32 times a second, or every 31.25 ms. With the application of these FixPaks,
the chip is now set up to generate an interrupt 128 times a second, or every
7.8125 ms. OS2_NTPD performs system clock corrections by actually resetting
the RTC chip at the appropriate time so as to step the time in increments as
small as one of the original ticks, or 31.25 ms, forward or backward. This
works beautifully for motherboards which emulate the Motorola RTC chip faith-
fully. However, some motherboards incorrectly emulated the chip and this
causes hiccups in the time adjustments performed by OS2_NTPD on occasion. For-
tunately, since the advent of the Pentium based motherboards with predominantly
Intel chipsets, this problem is not as widespread and is probably limited only
to older 486 systems. I have never seen a Pentium machine with an incorrectly
implemented RTC.
The difference is in how the chips behave after divisor reset, the method of
timestepping used by OS2_NTPD. Truly compatible implementations update the next
second 500 ms after divisor reset. The other implementations I have seen
update it immediately following divisor reset. This causes problems when a
small, single tick correction is being made and the actual time that it is
performed slips by a tick due to pre-emption, etc. This slip causes a whole
second error to occur instead of one tick. I have not successfully eliminated
these occurrences yet, however they are rare. They seem to be worst on heavily
loaded systems and systems running dial-up serial modems using PPP, which runs
at a very high priority.
Following the initial execution of OS2_NTPD, the data file rtc_type will hold
the results of its check for the type of RTC chip in your system. If the value
stored in rtc_type is zero, then your RTC is 100% compatible and you should
have no problems such as I have described. If the value is 500, then you
should expect to experience the one second hiccups from time to time if your
system is underpowered or heavily loaded or are accessing the Internet via dial-
up modem.
III. OPERATION
OS2_NTPD may be executed in one of two ways:
1) From the command line using a single server, with these arguments as so:
os2_ntpd.exe [ntp server(name or dotted decimal)
initial polling interval (integer seconds)
number of requests to send (integer)]
where: "ntp server" is the IP address of the NTP server, i.e.
tick.usno.navy.mil or 206.54.0.21
"initial polling interval" is the number of seconds between requests
to the server. It should be a power of two, such as 2, 4, 8, 16 etc.
"number of requests to send" is how many times to request time from
the server, if 0 is entered then requests will be sent indefinitely
All of these arguments must be present on the command line, separated by spaces.
There are no defaults.
2) From the command line with no arguments. When executed this way, OS2_NTPD
looks for the data file cfg_data in the current directory. If it is not found,
then an error message is displayed in the window. If it is found, and its
format is correct, then OS2_NTPD will display the contents of the file in the
window. A sample cfg_data file:
cfg_data
poll interval = 16
tick.usno.navy.mil
tock.usno.navy.mil
time.nist.gov
206.54.0.21
Each line must appear exactly as shown, terminated by a CR and LF. Up to 22
NTP servers may be listed following the poll_interval line. A single CR and LF
should follow the last server name.
Of course, a Workplace Shell program object may be created allowing execution
via mouse clicks, and a copy of the program object could be dragged to the
Startup Folder to allow automatic invocation following each boot up.
The OS2_NTPD User Interface
After reading the cfg_data file and displaying the server list, the
program will display an interface screen. This screen is a standard 25 line by
80 character text mode window, divided into three regions. The top
region consists of thirteen lines which display decoded packets, and the list
of NTP servers. The next region consists of three lines displaying output
status information such as timeouts, reply packets which are indicating an
alarm state, ensemble statistics, etc. The bottom five lines make up a
function key driven menu with up to twelve selections, not all of which are in
use at this time. The current active function keys are:
F1 Show Next Pkt -- Pressing this key will display the decoded packet
received from the first server from which a reply was
received in the current polling interval. Pressing it
again will display the next one and so on. Underneath the
raw packet information are displayed the server specific
timing statistics: the current server - client offset
measurement in seconds, the standard deviation of those
measurements, and the maximum and minimum measurements.
F2 Show Prev Pkt -- Pressing this key will display the decoded packet
received from the last server from which a reply was
received in the current polling interval. Pressing it
again will display the previous one and so on.
F6 Quick Sync -- Pressing this key will enable an instantaneous "jam sync"
of the system clock based on the next ensemble of replies
received from the active servers. The default behavior
if this key is not pressed is to propagate the ensembled
replies through a phase locked loop filter which will
slowly bring the system clock in line with the NTP
servers. The Quick Sync function is similar to NTPDATE
in that it is used to establish a starting
synchronization which is then refined based on further
averaging of NTP server replies and gradual corrections.
F7 Show Peers -- Pressing this key will display a list of the peers which
were active during the current polling interval.
F10 Enable Debug -- Pressing this key will enable logging of suspect reply
packets to the file "suspects". This logfile will be
opened for appending and closed after each polling
interval. Pressing the key again will suspend logging
to this file.
F11 Open LogFile -- Pressing this key the first time will open a logfile that
is named with the current ntp second. This logfile will
be opened for appending and closed after each polling
interval and contains the reduced timing data from each
of the servers in the cfg_data file, as well as ensemble
statistics. Once the logfile is open, pressing the key
again will close the file permanently.
F12 About -- Pressing this key will display information about this
program.
IV. THEORY OF OPERATION
Interested users should consider downloading the RFCs relating to network
timing written by David Mills of the University of Delaware. These cover in
gory detail the inner workings of the NTP. Mills also maintains a website,
http: //www.eecis.udel.edu/~ntp/ which is a vast repository of NTP related lore
and entertainment. OS2_NTPD operates based on version 3.0 of the NTP as
described in RFC 1305. Here I will only mention that the cornerstone of the
NTP is server diversity. The benefits of statistical ensembling and clustering
are not available if only one server is being polled. OS2_NTPD allows up to 22
servers to be configured for this reason.
OS2_NTPD maintains stability measurements on each server being used to set the
client clock. These stability measures are used to calculate weighting of the
individual server's contribution to the overall ensemble. Noisy servers
receive less weighting, quiet ones more. Further, due to the ordering of
the procedures, when a measurement comes in from a server, its weight is
updated first, then the measurement is added into the ensemble based on
the new weight. This provides a measure of immunity from bad server replies
since they are de-weighted prior to being used.
Once an ensemble measurement has been synthesized, it is passed to the phase
locked loop which controls the system clock. The phase locked loop implements
averaging of the NTP server reply data across time as opposed to the ensembling
algorithm which implements averaging across multiple servers. Initially the
PLL operates fairly quickly and updates the RTC at the rate specified by the
initial polling interval parameter provided in the cfg_data file or from the
command line. Once the client clock has been pulled within a tick (31.25 ms)
then the polling interval is lengthened by a factor of two. Each time the
ensemble measurement is within a tick, the polling interval is again lengthened
until it reaches 256 seconds, beyond which it does not extend. After the
polling interval has reached 256 seconds, PLL averaging is further extended by
modifying the coefficients in the digital loop filter. These are allowed to
extend until the PLL equivalent averaging time has reached 13401 seconds.
The main reason for setting the averaging time so long is to allow an accurate
measurement of the frequency offset of the client clock timebase. This
frequency offset has been referred to as "skew" in the Mills literature.
Unfortunately, the file created by the Unix versions of NTP containing
this skew term is called NTPDRIFT. Drift has actually been defined by the
global time and frequency community to mean the change in frequency of an
oscillator as a function of time, not its change in phase. So as not to
confuse those who have dealt with the various ports of Mills' NTP client
daemons, I have retained the " drift" naming convention for the file which
holds the fractional frequency offset of the client clock timebase.
OS2_NTPD uses this "drift" to extrapolate the behavior of the client clock when
no servers are available, so that corrections may continue to be made to the
clock to compensate for its assumed constant frequency error. In addition,
after a power outage, OS2_NTPD checks the timestamp in the "drift" file to
determine the length of the outage and will apply a correction based on the
outage duration and the fractional frequency offset which was stored in the
"drift" file. This approach is not fool proof, since corrections made
manually or by other programs during the outage of OS2_NTPD operation will not
be known to OS2_NTPD. Also, the frequency of the crystal oscillator inside of
the PC will be different when the power is applied as compared to when it is
not since the temperature inside the PC is dependent upon this.
Current Known Deficiencies in this version of the OS2_NTPD Client NTP:
1) The Leap Indicator bits are currently used only to detect server alarm
condition. No attempt is made to transparently implement any leap second event
at the correct time. This may be fixed in the future when more servers
properly indicate leap second events in these bits, which is not the case now!
2) The movement of time from Standard to Daylight and vice versa currently
propagates through the PLL loop filter and so takes a slow journey--maybe an
hour or so to get there. Will fix this eventually, but recommend that you do
not run your workstations on anything but Standard time, be it local or UTC.
2) No preference is currently given to servers based on their operating NTP
stratum level or root dispersion.
V. VERSION HISTORY
Bugfixes included in version 1.2 of OS2_NTPD
1) This version fixes the problems which were introduced when IBM changed
the tick rate of the RTC from 32 Hz to 128 Hz. The program now detects the
rate at which the RTC has been set to generate an interrupt and operates ap-
propriately for either case. One would think that the new higher rate would
allow an improvement in the setting of the clock, however the opposite is the
case. With the introduction of the higher tick rate, timetagging resolution
has been improved, so that calls to ftime() now return a precision of 10 ms.
Unfortunately, the other half of the problem, the ability to have something
done at a certain time using a timer function like DosSleep(), has not been
improved to the 10 ms level. The net effect is that there is more uncertainty
now in the setting of the RTC chip, so that typical performance is still at the
30 ms level.
Bugfixes included in version 1.1 of OS2_NTPD:
1) Some versions of OS/2 Warp Connect with various FixPacks at about 17 were
unable to run version 1.0 of the program, aborting with a "Stack Overflow"
message immediately following start-up. I changed the compiler from Borland
1.5 to IBM VAC++ 3.0, increased the stacksize in the threads and rearranged the
operation of the threads to eliminate the possibility of clean-up not being
performed. These systems are now able to run the program but there are still
some questions concerning memory leakage and system lock-ups on those same
systems. I will be welcoming any feedback as to whether I have fixed those
problems!
2) Borland did not do a very good job on the TZ environment variable in
their tzset() routine, choosing to have it handle only North American time zone
changes properly. Since changing to the IBM compiler for this version,
OS2_NTPD fully supports the TZ environment variable as described in this manual
so that both standard time and daylight time may work anywhere in the world if
the TZ variable is set up properly.
3) The REF ID field of the NTP packet was not being decoded properly with
servers operating at Stratum 2 or higher in version 1.0 of OS2_NTPD. It should
have shown the IP address of the server to which that server is peered rather
than the ascii clock type code like GPS or ACTS as would be done for Stratum 1
servers.
4) Some users with non-compatible RTC implementations have experienced the
one second hiccups in the RTC correction process that is described in this
manual. In version 1.1, I have managed to reduce them to an acceptable
level on my machines by giving up some of the resolution of the correction.
What this amounts to is that when I detect the RTC type, if it is a non-
compatible one, I perform two tick clock adjustments instead of single tick
adjustments. Due to the subleties of the adjustment process, this still allows
me to maintain an accuracy of about one tick, or 31.25 ms but greatly reduces
the frequency of the hiccups.
5) Fixed a potential string overflow problem when extremely large offsets
between the local clock and a server were being displayed.
DISCLAIMER!!!
The author makes no claims concerning suitability of this program for any use.
OS2_NTPD is offered for your use "as is", with no expressed or implied
warranties or guarantees of any kind. The author will assume no liability for
damages either from the direct use of this product or as a consequence of the
use of this product.