TimeSync Service - an NT service for keeping the clock in sync

1. Introduction

TimeSync is an NT service that keeps the local clock of the machine in
sync with a reference source. Currently, time reference sources may be
one of the following: the PDC of a domain, a specific NT machine, a
unix (or any) machine that understands TCP and has a time server
(RFC868) or an NTP server (RFC 1305). As a service it does not require
that a user be logged in: it starts off as soon as the machine boots
up and runs unobtrusively in the background. Before installing the
software please read the rest of this document.

The current version of TimeSync is 0.6 dated 7 August 1995.


2. Prerequisites

To install the service the user has to have sufficient privilege i.e.
Administrator rights. A fairly accurate time source is required.  This
could be a machine with a radio clock or synchronizes with one which
does. Please check the time of the machine where you intend to install
TimeSync and ensure that it within 10 minutes of the wall clock time.
The reason for this is that TimeSync will not change the time if the
difference between the local clock and the remote machine exceeds 10
minutes. This is intentional and done to avoid changing the clock if
the reference source is wildly off-course. The normal drift of a
computer clock should not exceed 8 seconds a day.


3. Installation

Copy the executable (TimeSync.exe) to a suitable directory on the local
disk.  The suggested place is %SYSTEMROOT%\system32. Change directory
to wherever you copied it to and type "TimeSync /?". You should see a
brief list of accepted arguments. Now type
	TimeSync /install <time source>
where <time source> is one of the following
	/domain=<domain name>
	/nt_machine=\\<nt machine name>
	/tcp_machine=<unix machine name>
	/ntp_machine=<ntp machine name>

For example, "TimeSync /install /domain=sales" will use the PDC of the
domain sales. If <time source> is left empty the domain controller of
the machine will be used as the time source.

For other parameters that might be useful at your site check the
section titled "Command line arguments". If you have NT domains I
recommend that servers be synchronized with a machine outside the
domain and workstations should use their PDC (i.e. leave the <time
source> specification empty).

If installation is successful you should see a message to that effect
in the console window. Open the "Control Panel | Services" applet and
click on TimeSync in the list of available services. By default, it
will automatically start up when the machine is booted. If manual
startup is required, click on Startup... and change the radio button in
the dialog box.  In the services window click on "Start". Within 5
seconds the status should show "Started". If an error occurs check the
event log for details.

Once it is successfully started check the event log. You should see a
startup message. By default, syncing is performed a randomly chosen time
between 05:00 and 06:00 local time. See section Remarks for details on
why this is done. If you would like it to sync at a different time
specify it by adding /at=<time> to the command line. In order to sync
as soon as it starts use the time 0:0:0.  Thus, /at=15:30 will cause it
to sync between 15:30 and 15:31; /at=0:0:0 will make it sync as soon as
the service starts.


4. Maintenance

Check the log once a week to ensure that TimeSync is running
smoothly.  You should only see 'informational' messages that the clock
has been set. If an error is reported the message there should be
self-explanatory. The value for the deviation should be within a few
seconds.


5. Deinstallation

Stop TimeSync in "Control Panel | Services" if it is currently
running.  In a console window type "TimeSync /remove". The service will
be removed and all the registry entries that were added during the
install phase will be cleaned up. If errors occur an appropriate
message will be displayed.


6. Remarks

The accuracy depends very much on the source that is used as the time
source.  If /tcp_machine is used in the command line one could expect
an accuracy of +- 1 second. If /ntp_machine is used on the command line
the accuracy could be as high as +- 30 milliseconds. As the time used
by TimeSync is UTC you can use a time source that is in another time
zone. The network delay is taken into consideration when calculating
the time for all except NTP sources. In other words, half of the time
required from the transmission of the request to the receipt of the
reply is added to the time. Caveat: this is approximate as it is
impossible to know what the real delay was. The assumptions here are
that the time for the transmission and reply are the same and, further,
that the remote computer does not require any time to answer the
request. In practice, however, these assumptions do not distort the
result by any appreciable amount.

The default syncing time is chosen at random between 05:00 and 06:00
local time. Why random? So that a whole network of machines with
TimeSync do not try to synchronize at the same time. Why between 05:00
and 06:00? So that the clock is changed when the machine is relatively
idle.

This version of TimeSync has been tested with NT 3.5 (build 807) and
NT 3.51 (build 1057). 

As Win95 and Win32s systems do not support services, TimeSync will not
run on them. TimeSync is meant only for NT systems. Should there be
sufficient demand for a Win95 port I might undertake to do it.


7. Command line arguments

Some of the arguments have been discussed earlier. For normal usage
those are sufficient. Special circumstances may require the advanced
control arguments dealt with in this section.

/install
	installs the service. Should be used only when installing the
	service.
/remove
	removes the service. See the section on deinstallation for
	details.
/domain=<domain name>
	specifies that the time source should be the PDC of that
	domain.
/nt_machine=\\<nt machine name>
	to use that node as time source
/tcp_machine=<machine name>
	to use port 37 of that unix (or whatever) node as time source
/ntp_machine=<machine name>
	to use an NTP server as time source 
/period=<hours>:<minutes>:<seconds>
	to specify update frequency. The default is 24 hours. That is,
	TimeSync will synchronize once a day. /period=8:0:0 will cause
	it to synchronize every 8 hours.
/at=<hours>:<minutes>:<seconds>
	to specify the start time for syncing. If this argument is
	omitted the default is some random time between 05:00 and
	06:00. If minutes or seconds are left out a random number will
	be chosen for the omitted component. To sychronize at start-up
	specify /at=0:0:0. This will prevent TimeSync from waiting.
	Specify this option if the workstation you are installing
	TimeSync on is turned off at the end of the day.
/adjust
	to specify that TimeSync should slowly adjust the clock to make
	up for the deviation rather than setting the clock. This will
	cause the NT clock to be speeded up or slowed down by a small
	amount during each clock interrupt (usually every 10
	milliseconds). Depending on the actual deviation this might
	take up to 4 hours or half of the update frequency (specified
	with /period).  This feature is useful if there are programs
	that depend on the fact that time cannot go back. For example,
	make looks at the modification time of files in order to decide
	what has to be generated anew.
/immediate
	to run the program without installing a service. It
	synchronizes once and then exits. This is mainly used for
	testing. It ignores the /at argument, if specifed, and assumes
	that /at=0:0:0 was entered (synchronize right away).
/log=<device or file>
	to redirect the messages from TimeSync to another file or device.
	The default is console during interactive use and the event log
	when it is running as a service. To specify the console type
	/log=Console, for the event log use /log=EventLog or to output to
	a file use /log=somefile.log. The file will be handled like a
	circular buffer of size 10000 bytes; when it gets to the end it
	will start from the beginning. Each line starts with the date,
	time and severity.
/trace
	to enable tracing. Outputs additional information to the current
	log device.

I set up my machine with the following command line arguments:
TimeSync /install /at=0:0:0 /period=8:0:0 /adjust /tcp_machine=horus
         /trace /log=timesync.log
	  

8. Notes on the implementation

The TimeSync executable contains the installer, deinstaller, the
service itself and the text of the event log messages. It stores
registry parameters in the following key:
	HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TimeSync.
The command line parameters that were entered during installation will
be under the Parameters key. When running as a service it uses the
event log to output messages; if used interactively the default log
device is the console. In both cases messages may be redirected to a
file.


9. Possible Improvements

A control panel applet would be nice.


10. Contacting me

I would welcome any constructive criticism regarding the program, its
usefulness to you and any assorted ideas you have which might improve
it. However, I cannot guarantee a response and, further, I cannot
guarantee that I will fix bugs and/or incorporate your ideas into a
future version.

Mail address:
	Raju Varghese
	Intellisoft Inc.
	Stoeckmattstr. 3
	CH-5316 Leuggern
	Switzerland

Fax:        +41 56 455 140
email:      raju@intellisoft.ch
compuserve: 100116,1001


11. Revisions

0.4 first public release

0.5 added tracing and redirection of messages to different log
    device. Fixed problem with adjust that caused the previous
    time to be restored. This seems to be a 'feature' of NT: if
    time adjustment is disabled NT seems to get the old time
    from somewhere (presumably the HW clock) and restore it once
    an hour. This defeated the synchronization performed by
    TimeSync.
0.6 TimeSync occassionally crashed in the kernel dll when
    converting Unicode to 8-bit characters. I have not been able
    to acertain the reason for this and hence I have recoded that
    part. Also removed a trace output with the remote time after
    synchronization.


12. Legalese

TimeSync is supplied "as is" without warranty of any kind, either
expressed or implied, including, but not limited to, the implied
warranties of mechantability and fitness for a particular purpose. The
entire risk as to the quality and performance of the program is with
you. Should the program prove defective, you assume the cost of all
necessary servicing, repair or correction.


Copyright (c) 1994,1995 Raju Varghese, Intellisoft Inc., Switzerland
All Rights Reserved