readme.msntp

linux下的获取Internet time的程式

commands, the installation is finished!

You can use it as a simple unprivileged command to check the time, quite
independently of whether it is running as a time-updating daemon or server, or
whether you are running xntp.  You can run it in daemon mode without updating
the clock, to check for drift, but it may fail if the clock is changed under
its feet.  Unfortunately, you cannot listen to broadcasts without privilege.

If it is used with the -a option to keep the time synchronised, it is best to
run it as one of root's cron jobs - for many systems, running it once a day
should be adequate, but it will depend on the reliability of the local clock.
The author runs it this way with -a and -x - see below.

If it is used with the -r option to set the time (instead of the rdate or date
commands), it should be used interactively and either on a lightly loaded
system or at a high priority.  You should then check the result by running it
in display mode.

You are advised NOT to run it with the -r option in a cron job, though this is
not locked out.  If you have to (for example under HP-UX before 10.0), be sure
to run it as the highest priority that will not cause other system problems and
set the maximum automatic change to as low a value as you can get away with.

WARNING: adjtime is more than a bit sick on many systems, and will ignore large
corrections, usually without any form of hint that it has done so.  It is often
(even usually) necessary to reset the clock to approximately the right time
using the -r option before using the -a and -x options to keep it correct.

It can be started as a time-updating daemon with the -a and -x options (or -r
and -x if you must), and will perform some limited drift correction.  In this
case, start it from any suitable system initialisation script and leave it
running.  Note that it will stop if it thinks that the time difference or drift
has got out of control, and you will need to reset the time and restart it by
hand.

In daemon mode, it will survive its time server or network disappearing for a
while, but will eventually fail, and will fail immediately if the network call
returns an unexpected error.  If this is a problem, you can start it (say,
hourly or nightly) from cron, and it will fail if it is already running
(provided that you haven't disabled or deleted the lock file).

If it is used as a server, it should be started from any suitable system
initialisation script, just like any other daemon.  It must be started after
the networking, of course.  To run it in both server modes, start one copy with 
the -B option and one with the -S option.


Simple Examples of Use
----------------------

Many people use it solely to check the time of their system, especially as a
cross-check on xntpd.  You do not need privilege and it will not cause trouble
to the local network, so you can use it on someone else's system!  You can
specify one server or several.  For example:

    msntp ntp.server.local ntp.server.neighbour

You can use it to check how your system is drifting, but it isn't very good at
this if the system is drifting very badly (in which case use the previous
technique and dc) or if you are running xntp.  You do not need privilege and it
will not cause trouble to the local network.  For example:

    msntp -x 120 -f /tmp/msntp.state ntp.server.local

More generally, it is used to synchronise the clock, in which case you DO need
root privilege.  It can be used in many ways, but the author favours running it
in daemon mode, started from a cron job, which will restart after power cuts
with no attention, and send a mail message (if cron is configured to do that)
when it fails badly.  For example, the author uses a root crontab entry on one
system of:

    15 0 * * * /bin/nice --10 /usr/local/bin/msntp -a -x 480 ntp.server.local

If you have a home computer, it can be set up to resynchronise each time you
dial up.  For example, the author uses a /etc/ppp/ip-up.d/msntp file on his
home Linux system of:

    #!/bin/sh
    sleep 60
    /bin/nice --10 /usr/local/sbin/msntp -r -P 60 ntp.server.local

-a would be better, but adjtime is broken in Linux.


Debugging or Hacking the Program
--------------------------------

Almost everybody who does this is likely to need to modify only the system
interfaces.  While they are messy, they are pretty simple and have a simple
specification.  This is documented in comments in the source.  This is
described above.

The main program SHOULD need no attention, though it may need the odd tweak to
bypass compiler problems - please report these, if you encounter any.  If
something looks odd while it is running, start by setting the -v option (lower
case), as for investigating network problems, and checking any diagnostics that
appear.  Note that most of it can be checked in display mode without harming
your system.

The client will sometimes give up, complaining about inconsistent timestamps or
similar.  This can be caused by the server being rebooted and similar glitches
to the time - unfortunately, there is no reliable way to tell an ignorable
fluctuation from a server up the spout.  If this happens annoyingly often,
the -V option may help tie down the problem.  In actual use, it is simplest
just to restart the client in a cron job!

If it needs more than this, then you will need to debug the source seriously.
Start by putting an icepack on your head and pouring yourself a large whisky!
While it is commented, it is not well commented, and much of the code interacts
in complex and horrible ways.  This isn't so much because it lacks 'structure'
as because one part needs to make assumptions about the numerical properties of
another.

The -W option (upper case) will print out a complete trace of everything it
does, and this should be enough to tie down the problem.  It does distort the
timing a bit, but not usually too badly.  However, wading through that amount
of gibberish (let alone looking at the source) is not a pleasant task.  If you
are pretty sure that you have a bug, you may tell the author, and he may ask
for a copy of the output - but he will reply rudely if you send thousands of
lines of tracing to him by Email!

Note that there are a fair number of circumstances where its error recovery
could be better, but is left as it is to keep the code simple.  Most of these
should be pretty rare.


Changes in Version 1.2
----------------------

The main change was the addition of the daemon mode for drift correction (i.e.
the -x option).  The daemon code is complex and has a lot of special-casing for
strange circumstances, not all of which are testable in practice.

A lot of the code was reordered while doing this.  The output was slightly
different - considerably different with -V.

The error estimation for broadcasts was modified, and should bear more relation
to reality.  It remains a guess, as there is no way to get decent error error
estimates under such circumstances.

The -B option is now in minutes, and has a different permissible range and
default value.

The argument consistency checking for broadcasts was tightened up a bit, and a
few other internal checks added.  These should not affect any reasonable
requirement.

A couple of new functions were added to the portability base, but they don't
use any non-standard new facilities.  However, the specification of the
functions has changed slightly.


Changes in Version 1.3
----------------------

The main change was the addition of the restarting facility for daemon mode
(i.e. the -f option), which is pretty straightforward.

There were also a lot of minor changes to the paranoia code in daemon mode, to
try to separate out the case of a demented server from network and other
'ignorable' problems.  These are not entirely successful.


Changes in Version 1.4 and 1.5
------------------------------

There turned out to be a couple of places where the author misunderstood the
specification of NTP, which affect only its use in server mode.  The main
change is to use stratum 15 instead of stratum 0.

And there were some more relaxations of the paranoia code, to allow for more
erratic servers, plus a kludge to improve restarting in daemon mode after a
period of down time has unsynchronised the clock.  There is also an
incompatible change to the debugging options to add a new level - the old -V
option is now -W, and -V is an intermediate one for debugging daemon mode - but
they are both hacker's facilities, and not for normal use.

Version 1.5 adds some very minor fixes.


Changes in Version 1.6
----------------------

The first change is support for multiple server addresses - it uses these in a
round-robin fashion.  This may be useful when you have access to several
servers, all of which are a bit iffy.  This means that the restart file format
is incompatible with msntp 1.5.

It has also been modified to reset itself automatically after detecting an
inconsistency in its server's timestamps, because the author got sick of the
failures.  It writes a comment to syslog (uniquely) in such cases.

The ability to query a daemon save file was added.

Related to the above, the -E argument has been redefined to mean an error bound
on various internal times (which is what it had become, anyway) and a -P option
introduced to be what the -E argument was documented to be.

The lock and save file handling have been changed to allow defaults to be set
at installation time, and to be overridable at run-time.  To disable these
at either stage, simply set the file names to the null string.

And there have been the usual changes for portability, as standards have been
modified and/or introduced.


Future Versions
---------------

There are unlikely to be any, except probably one to fix bugs in version 1.6.

I attempted to put support for intermittent connexions (e.g. dial-up) into the
daemon mode, but doing so needs so much code reorganisation that it isn't worth
it.  What needs doing for that is to separate the socket handling from the
timekeeping, so that they can be run asynchronously (either in separate
processes or threads), and to look up a network name and open a socket only
when prodded (and to close it immediately thereafter).  So just running it
with the -r option is the current best solution.

I also attempted to put support for the "Unix 2000" interfaces into the code.
Ha, ha.  Not merely do very few systems define socklen_t (needed for IPv6
support), but "Unix 2000" neither addresses the leap second problem nor even
provides an adjtime replacement!  Some function like the latter is critical,
not so much because of the gradual change, but because of its atomicity;
without it, msntp really needs to be made non-interruptible, and that brings in
a ghastly number of system-dependencies.

Realistically, it needs a complete rewrite before adding any more function.
And, worse, the Unix 'standards' need fixing, too.



Miscellaneous
-------------

Thanks are due to Douglas M. Wells of Connection Technologies for helping the
author with several IP-related conventions, to Sam Nelson of Stirling
University for testing it on some very strange systems, and to David Mills for
clarifying what the NTP specification really is.

Thanks are also due to several other people with locating bugs, finding
appropriate options for the Makefile and passing on extension code and
suggestions.  As I am sure to leave someone out, I shall not name anyone else.

Version 1.0 - October 1996.
Version 1.1 - November 1996 - mainly portability improvements.
Version 1.2 - January 1997 - mainly drift handling, but much reorganisation.
Version 1.3 - February 1997 - daemon save file, and some robustness changes.
Version 1.4 - May 1997 - relatively minor fixes, more diagnostic levels etc.
Version 1.5 - December 1997 - some very minor fixes
Version 1.6 - October 2000 - quite a few miscellaneous changes


Nick Maclaren,
University of Cambridge Computer Laboratory,
New Museums Site, Pembroke Street, Cambridge CB2 3QG, England.
Email:  [e-mail]
Tel.:  [phone]    Fax:  [phone]