PageRenderTime 76ms CodeModel.GetById 46ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/ntp/sntp/README

https://bitbucket.org/freebsd/freebsd-head/
#! | 536 lines | 407 code | 129 blank | 0 comment | 0 complexity | 528465953aae43a0396122bfdeb8d388 MD5 | raw file
  1SNTP (Simple Network Time Protocol Utility) - Version 1.6
  2----------------------------------------------------------
  3
  4Please read the file Copyright first.  Also note that the file RFC2030.TXT is
  5David Mills's copyright and not the author's - it is just a copy of the RFC
  6that is available from so many Internet archives.
  7
  8RFC 1305 (Network Time Protocol - NTP) is an attempt to provide globally
  9consistent timestamps in an extremely hostile environment; it is fiendishly
 10complicated and an impressive piece of virtuosity.  RFC 2030 (Simple Network
 11Time Protocol - SNTP) which supersedes RFC 1769 describes a subset of this that
 12will give excellent accuracy in most environments encountered in practice; it
 13uses only the obvious algorithms that have been used since time immemorial.
 14
 15WARNING: the text version of RFC 1305 is incomplete, and omits the tables that
 16are in the Postscript version.  Unfortunately, these contain the only copy of
 17some critical information.
 18
 19draft-mills-sntp-v4-00.txt is the next proposed revision of RFC 2030,
 20and the current goal is to have this code implement that specification.
 21
 22SNTP Servers - Some Little-Known Facts
 23--------------------------------------
 24
 25RFC 2030 states that SNTP clients should be used only at the lowest level,
 26which is good practice.  It then states that SNTP servers should be used only
 27at stratum 1 (i.e. top level), which is bizarre!  A far saner use of them would
 28be for the very lowest level of server, exporting solely to local clients that
 29do not themselves act as servers to ANY system (e.g. on a Netware server,
 30exporting only to the PCs that it manages).
 31
 32[There is missing language in the previous paragraph.  SNTP is designed
 33to be used in 2 cases: as a client at the lowest levels of the timing
 34hierarchy, or as a server of last resort at stratum 1 when connected to
 35a modem or radio clock.]
 36
 37[This is as far as I have updated this file as part of the upgrade.]
 38
 39If the NTP network were being run as a directed acyclic graph (i.e. using SNTP
 40rather than full NTP), with a diameter of D links and a maximum error per link
 41of E, the maximum synchronisation error would be D*E.  Reasonable figures for D
 42and E are 5 and 0.1 seconds, so this would be adequate for most uses.  Note
 43that the fact that the graph is acyclic is critical, which is one reason why
 44SNTP client/servers must NEVER be embedded WITHIN an NTP network.
 45
 46The other reason is that inserting SNTP client/servers at a low stratum (but
 47not the root) of an NTP network could easily break NTP!  See RFC 1305 for why,
 48but don't expect the answer to stand out at you.  It would be easy to extend
 49SNTP to a full-function client/server application, thus making it into a true
 50alternative to ntp, but this incompatibility is why it MUST NOT be done.
 51
 52The above does not mean that the SNTP approach is unsatisfactory, but only that
 53it is incompatible with full NTP.  The author would favour a complete SNTP
 54network using the SNTP approach, and the statistical error reduction used in
 55SNTP, but it actually addresses a slightly different problem from that
 56addressed by NTP.  TANSTAAFL.
 57
 58FINAL WARNING: do NOT use this program to serve NTP requests from outside the
 59systems that you manage.  If you do this, and manage to break the time
 60synchronisation on other people's systems, you will be regarded very
 61unfavourably.  Actually, this should be possible only if their NTP client is
 62completely broken, because SNTP does its damnedest to declare its packets as
 63the lowest form of NTP timestamp.
 64
 65
 66
 67SNTP and its Assumptions
 68-------------------------
 69
 70SNTP is intended to be a straightforward SNTP daemon/utility that is easy to
 71build on any reasonable Unix platform (and most near-Unix ones), whether or not
 72it has ever been ported to them before.  It is intended to answer the following
 73requirements, either by challenge and response or the less reliable broadcast
 74method:
 75
 76    A simple command to run on Unix systems that will check the time
 77    and optionally drift compared with a known, local and reliable NTP
 78    time server.  No privilege is required just to read the time and
 79    estimate the drift.
 80
 81    A client for Unix systems that will synchronise the time from a known,
 82    local and reliable NTP time server.  This is probably the most common
 83    one, and the need that caused the program to be written.
 84
 85    A server for Unix systems that are synchronised other than by NTP
 86    methods and that need to synchronise other systems by NTP.  This is
 87    the classroom of PCs with a central server scenario.  It is NOT
 88    intended to work as a peer with true NTP servers, and won't.
 89
 90    A simple method by which two or more Unix systems can keep themselves
 91    synchronised using what is becoming a standard protocol.  Yes, I know
 92    that there are half-a-dozen other such methods.
 93
 94    A base for building non-Unix SNTP clients.  Some 3/4 of the code
 95    (including all of the complicated algorithms and NTP packet handling)
 96    should work, unchanged, on any system with an ANSI/ISO C compiler.
 97
 98There are full tracing facilities and a lot of paranoia in the code to check
 99for bad packets (more than in ntp) which may need relaxing in the light of
100experience.  Unfortunately, RFC 1305 does not include a precise description of
101the data protocol, despite its length, and there are some internal
102inconsistencies and differences between it and RFC 2030 and ntp's behaviour.
103
104WARNING: SNTP has not been tested in conjunction with ntp broadcasts or ntp
105clients, as the ability to do so was not available to the author.  It is very
106unlikely that it won't work, but you should check.  Much of the paranoid code
107is only partially tested, too, because it is dealing with cases that are very
108hard to provoke.
109
110It assumes that the local network is tolerably secure and that any accessible
111NTP or SNTP servers are trustworthy.  It also makes no attempt to check that
112it has been installed and is being used correctly (e.g. at an appropriate
113priority) or that the changes it makes have the desired effect.  When you first 
114use it, you should both run it in display mode and use the date command as a
115cross-check.
116
117Furthermore, it does not attempt to solve all of the problems addressed by the
118NTP protocol and you should NOT use it if any of those problems are likely to
119cause you serious trouble.  If they are, bite the bullet and implement ntp, or
120buy a fancy time-server.
121
122
123Building SNTP
124-------------
125
126The contents of the distribution are:
127
128README        -    this file
129Copyright     -    the copyright notice and conditions of use
130Makefile      -    the makefile, with comments for several systems
131header.h      -    the main header (almost entirely portable)
132kludges.h     -    dirty kludges for difficult systems
133internet.h    -    a very small header for internet.c and socket.c
134main.c        -    most of the source (almost entirely portable)
135unix.c        -    just for isatty, sleep and locking
136internet.c    -    Internet host and service name lookup
137socket.c      -    the Berkeley socket code
138sntp.1        -    the man page
139RFC2030.TXT   -    the SNTPv4 specification
140
141All you SHOULD need to do is to uncomment the settings in file Makefile for
142your system or to add new ones.  But real life is not always so simple.  As
143POSIX does not yet define sub-second timers, Internet addressing facilities,
144sockets etc., the code has to rely on the facilities described in the
145ill-defined and non-standard 'X/Open' documents and the almost totally
146unspecified 'BSD' extensions.
147
148Most hacks should be limited to the compiler options (e.g. setting flags like
149_XOPEN_SOURCE), but perverse systems may need additions to kludges.h - please
150report them to the author.  See Makefile and kludges.h for documentation on
151the standard hacks - there only 6, and most are only for obsolete systems.
152But, generally, using the generic set of C options usually works with no
153further ado.
154
155
156Sick, Bizarre or non-Unix Systems
157---------------------------------
158
159A very few Unix systems and almost all non-Unix systems may need changes to the
160code, such as:
161
162    If the system doesn't have Berkeley sockets, you will need to replace
163    socket.c and possibly modify internet.h and internet.c.  All of the
164    systems for which the author needs this have Berkeley sockets.
165
166    NTP is supposedly an Internet protocol, but is not Internet specific.
167    For other types of network, you will need to replace internet.c and
168    probably modify internet.h.
169
170    If the system doesn't have gettimeofday or settimeofday, you will
171    need to modify timing.c.  If it doesn't have adjtime (e.g. HP-UX
172    on PA-RISC before 10.0), you can set -DADJTIME_MISSING and the code
173    will compile but the -a option will always give an error.
174
175    If the system has totally broken signal handling, the program will
176    hang or crash if it can't reach its name server or responses time
177    out.  You may be able to improve matters by hacking internet.c and
178    socket.c, but don't bet on it.
179
180    If the the program won't be able to create files in /etc when
181    updating the clock, you can use another lock file or even set
182    -DLOCKFILE=NULL, which will disable the locking code entirely.  On
183    systems that have it, using /var/run would be better than /etc.
184
185    If the the program hangs when flushing outstanding packets (which
186    you can tell by setting -W), it may help to set -DNONBLOCK_BROKEN.
187    This seems needed only for obsolete systems, like Ultrix.
188
189    If the system isn't Unix, even vaguely, you will probably need to
190    modify all of the above, and unix.c as well.
191
192    Note that adjtime is commonly sick, but you don't need to change the
193    code - just use the -r option whan making large corrections (see below
194    for more details).
195
196Any changes needed to header.h or main.c are bugs.  They may be bugs in the
197code or in the compiler or libraries, but they are bugs.  Please prod the
198people responsible and tell the author, who may be able to bypass them cleanly
199even if they aren't bugs in his code.  The code also makes the following
200assumptions, which would be quite hard to remove:
201
202    8-bit bytes.  Strictly, neither ANSI/ISO C nor POSIX require these,
203    and there were some very early versions of Unix on systems with other
204    byte sizes.  But, without a defined sub-byte facility in C, ....
205
206    At least 32-bit ints.  Well, actually, this wouldn't be too hard to
207    remove.  But most Unix programs make this assumption, and I have very
208    little interest in the more rudimentary versions of MS-DOS etc.
209
210    An ANSI/ISO C compiler.  It didn't seem worth writing dual-language
211    code in 1996.  Tough luck if you haven't got one.
212
213    Tolerably efficient floating-point arithmetic, with at least 13 digits
214    (decimal), preferably 15, in the mantissa of doubles.  Ditto.  If you
215    want to port this to a toaster, please accept my insincerest sympathies
216    and don't bother me.
217
218    A trustworthy local network.  It does not check for DNS, Ethernet,
219    packet or other spoofing, and assumes that any accessible NTP or SNTP
220    servers are properly synchronised.
221
222
223Warnings about Installation and Use
224-----------------------------------
225
226Anyone attempting to fiddle with the clock on their system should already know
227how to write system administration scripts, install daemons and so on.  There
228are a few warnings:
229
230    Don't use the broadcast modes unless you really have to, as the
231    client-server modes are far more reliable.  The broadcast modes were
232    implemented more for virtuosity (a.k.a. SNTP conformance) than use.
233    In particular, the error estimates are mere guesses, and may be low
234    or even very low.  And even reading broadcasts needs privilege.
235
236    The program is not intended to be installed setuid or setgid, and
237    doing so is asking for trouble.  Its ownerships and access modes are
238    not important.  It need not be run by root for merely displaying the
239    time (even in daemon mode).
240
241    The program does not need to run at a high priority (low in Unix
242    terms!) even when being used to set the clock or as a server, except
243    when the '-r' option is  used.  However, doing so may improve its
244    accuracy.
245
246    Unlike NTP, the SNTP protocol contains no protection against
247    client-server loops.  If you set one up, your systems will spin
248    themselves off into a disconnected vortex of unreality!
249
250    It will get very confused if another process changes the local time
251    while it is running.  There is some locking code in unix.c to prevent
252    this program doing this to itself, but it will protect only against
253    some errors.  However, the remaining failures should be harmless.
254
255    Don't run it as a server unless you REALLY know what you are doing.
256    It should be used as a server only on a system that is properly
257    synchronised, by fair means or foul.  If it isn't, you will simply
258    perpetrate misinformation.  And remember that broadcasts are most
259    unpopular with overloaded administrators of overloaded networks.
260
261    Watch out for multi-server broadcasts and systems with multiple ports
262    onto the same Ethernet; there is some code to protect against this,
263    but it is still easy to get confused.
264
265    Don't put the lock file onto an automounted partition or delete it by
266    hand, unless you really want to start two daemons at the same time.
267    Both will probably fail horribly if you do this.
268
269    The daemon save file is checked fairly carefully, but should be in a
270    reasonably safe directory, unless you want hackers to cause trouble.
271    /tmp is safe enough on most systems, but not all - /etc is better.
272
273
274Installing and Using the Program
275--------------------------------
276
277Start by copying the executable and man page to where you want them.  If you
278want only to display the time and as a replacement for the rdate or date
279commands, the installation is finished!
280
281You can use it as a simple unprivileged command to check the time, quite
282independently of whether it is running as a time-updating daemon or server, or
283whether you are running ntp.  You can run it in daemon mode without updating
284the clock, to check for drift, but it may fail if the clock is changed under
285its feet.  Unfortunately, you cannot listen to broadcasts without privilege.
286
287If it is used with the -a option to keep the time synchronised, it is best to
288run it as one of root's cron jobs - for many systems, running it once a day
289should be adequate, but it will depend on the reliability of the local clock.
290The author runs it this way with -a and -x - see below.
291
292If it is used with the -r option to set the time (instead of the rdate or date
293commands), it should be used interactively and either on a lightly loaded
294system or at a high priority.  You should then check the result by running it
295in display mode.
296
297You are advised NOT to run it with the -r option in a cron job, though this is
298not locked out.  If you have to (for example under HP-UX before 10.0), be sure
299to run it as the highest priority that will not cause other system problems and
300set the maximum automatic change to as low a value as you can get away with.
301
302WARNING: adjtime is more than a bit sick on many systems, and will ignore large
303corrections, usually without any form of hint that it has done so.  It is often
304(even usually) necessary to reset the clock to approximately the right time
305using the -r option before using the -a and -x options to keep it correct.
306
307It can be started as a time-updating daemon with the -a and -x options (or -r
308and -x if you must), and will perform some limited drift correction.  In this
309case, start it from any suitable system initialisation script and leave it
310running.  Note that it will stop if it thinks that the time difference or drift
311has got out of control, and you will need to reset the time and restart it by
312hand.
313
314In daemon mode, it will survive its time server or network disappearing for a
315while, but will eventually fail, and will fail immediately if the network call
316returns an unexpected error.  If this is a problem, you can start it (say,
317hourly or nightly) from cron, and it will fail if it is already running
318(provided that you haven't disabled or deleted the lock file).
319
320If it is used as a server, it should be started from any suitable system
321initialisation script, just like any other daemon.  It must be started after
322the networking, of course.  To run it in both server modes, start one copy with 
323the -B option and one with the -S option.
324
325
326Simple Examples of Use
327----------------------
328
329Many people use it solely to check the time of their system, especially as a
330cross-check on ntpd.  You do not need privilege and it will not cause trouble
331to the local network, so you can use it on someone else's system!  You can
332specify one server or several.  For example:
333
334    msntp ntp.server.local ntp.server.neighbour
335
336You can use it to check how your system is drifting, but it isn't very good at
337this if the system is drifting very badly (in which case use the previous
338technique and dc) or if you are running ntp.  You do not need privilege and it
339will not cause trouble to the local network.  For example:
340
341    sntp -x 120 -f /tmp/msntp.state ntp.server.local
342
343More generally, it is used to synchronise the clock, in which case you DO need
344root privilege.  It can be used in many ways, but the author favours running it
345in daemon mode, started from a cron job, which will restart after power cuts
346with no attention, and send a mail message (if cron is configured to do that)
347when it fails badly.  For example, the author uses a root crontab entry on one
348system of:
349
350    15 0 * * * /bin/nice --10 /usr/local/bin/sntp -a -x 480 ntp.server.local
351
352If you have a home computer, it can be set up to resynchronise each time you
353dial up.  For example, the author uses a /etc/ppp/ip-up.d/sntp file on his
354home Linux system of:
355
356    #!/bin/sh
357    sleep 60
358    /bin/nice --10 /usr/local/sbin/sntp -r -P 60 ntp.server.local
359
360-a would be better, but adjtime is broken in Linux.
361
362
363Debugging or Hacking the Program
364--------------------------------
365
366Almost everybody who does this is likely to need to modify only the system
367interfaces.  While they are messy, they are pretty simple and have a simple
368specification.  This is documented in comments in the source.  This is
369described above.
370
371The main program SHOULD need no attention, though it may need the odd tweak to
372bypass compiler problems - please report these, if you encounter any.  If
373something looks odd while it is running, start by setting the -v option (lower
374case), as for investigating network problems, and checking any diagnostics that
375appear.  Note that most of it can be checked in display mode without harming
376your system.
377
378The client will sometimes give up, complaining about inconsistent timestamps or
379similar.  This can be caused by the server being rebooted and similar glitches
380to the time - unfortunately, there is no reliable way to tell an ignorable
381fluctuation from a server up the spout.  If this happens annoyingly often,
382the -V option may help tie down the problem.  In actual use, it is simplest
383just to restart the client in a cron job!
384
385If it needs more than this, then you will need to debug the source seriously.
386Start by putting an icepack on your head and pouring yourself a large whisky!
387While it is commented, it is not well commented, and much of the code interacts
388in complex and horrible ways.  This isn't so much because it lacks 'structure'
389as because one part needs to make assumptions about the numerical properties of
390another.
391
392The -W option (upper case) will print out a complete trace of everything it
393does, and this should be enough to tie down the problem.  It does distort the
394timing a bit, but not usually too badly.  However, wading through that amount
395of gibberish (let alone looking at the source) is not a pleasant task.  If you
396are pretty sure that you have a bug, you may tell the author, and he may ask
397for a copy of the output - but he will reply rudely if you send thousands of
398lines of tracing to him by Email!
399
400Note that there are a fair number of circumstances where its error recovery
401could be better, but is left as it is to keep the code simple.  Most of these
402should be pretty rare.
403
404
405Changes in Version 1.2
406----------------------
407
408The main change was the addition of the daemon mode for drift correction (i.e.
409the -x option).  The daemon code is complex and has a lot of special-casing for
410strange circumstances, not all of which are testable in practice.
411
412A lot of the code was reordered while doing this.  The output was slightly
413different - considerably different with -V.
414
415The error estimation for broadcasts was modified, and should bear more relation
416to reality.  It remains a guess, as there is no way to get decent error error
417estimates under such circumstances.
418
419The -B option is now in minutes, and has a different permissible range and
420default value.
421
422The argument consistency checking for broadcasts was tightened up a bit, and a
423few other internal checks added.  These should not affect any reasonable
424requirement.
425
426A couple of new functions were added to the portability base, but they don't
427use any non-standard new facilities.  However, the specification of the
428functions has changed slightly.
429
430
431Changes in Version 1.3
432----------------------
433
434The main change was the addition of the restarting facility for daemon mode
435(i.e. the -f option), which is pretty straightforward.
436
437There were also a lot of minor changes to the paranoia code in daemon mode, to
438try to separate out the case of a demented server from network and other
439'ignorable' problems.  These are not entirely successful.
440
441
442Changes in Version 1.4 and 1.5
443------------------------------
444
445There turned out to be a couple of places where the author misunderstood the
446specification of NTP, which affect only its use in server mode.  The main
447change is to use stratum 15 instead of stratum 0.
448
449And there were some more relaxations of the paranoia code, to allow for more
450erratic servers, plus a kludge to improve restarting in daemon mode after a
451period of down time has unsynchronised the clock.  There is also an
452incompatible change to the debugging options to add a new level - the old -V
453option is now -W, and -V is an intermediate one for debugging daemon mode - but
454they are both hacker's facilities, and not for normal use.
455
456Version 1.5 adds some very minor fixes.
457
458
459Changes in Version 1.6
460----------------------
461
462The first change is support for multiple server addresses - it uses these in a
463round-robin fashion.  This may be useful when you have access to several
464servers, all of which are a bit iffy.  This means that the restart file format
465is incompatible with msntp 1.5.
466
467It has also been modified to reset itself automatically after detecting an
468inconsistency in its server's timestamps, because the author got sick of the
469failures.  It writes a comment to syslog (uniquely) in such cases.
470
471The ability to query a daemon save file was added.
472
473Related to the above, the -E argument has been redefined to mean an error bound
474on various internal times (which is what it had become, anyway) and a -P option
475introduced to be what the -E argument was documented to be.
476
477The lock and save file handling have been changed to allow defaults to be set
478at installation time, and to be overridable at run-time.  To disable these
479at either stage, simply set the file names to the null string.
480
481And there have been the usual changes for portability, as standards have been
482modified and/or introduced.
483
484
485Future Versions
486---------------
487
488There are unlikely to be any, except probably one to fix bugs in version 1.6.
489
490I attempted to put support for intermittent connexions (e.g. dial-up) into the
491daemon mode, but doing so needs so much code reorganisation that it isn't worth
492it.  What needs doing for that is to separate the socket handling from the
493timekeeping, so that they can be run asynchronously (either in separate
494processes or threads), and to look up a network name and open a socket only
495when prodded (and to close it immediately thereafter).  So just running it
496with the -r option is the current best solution.
497
498I also attempted to put support for the "Unix 2000" interfaces into the code.
499Ha, ha.  Not merely do very few systems define socklen_t (needed for IPv6
500support), but "Unix 2000" neither addresses the leap second problem nor even
501provides an adjtime replacement!  Some function like the latter is critical,
502not so much because of the gradual change, but because of its atomicity;
503without it, msntp really needs to be made non-interruptible, and that brings in
504a ghastly number of system-dependencies.
505
506Realistically, it needs a complete rewrite before adding any more function.
507And, worse, the Unix 'standards' need fixing, too.
508
509
510
511Miscellaneous
512-------------
513
514Thanks are due to Douglas M. Wells of Connection Technologies for helping the
515author with several IP-related conventions, to Sam Nelson of Stirling
516University for testing it on some very strange systems, and to David Mills for
517clarifying what the NTP specification really is.
518
519Thanks are also due to several other people with locating bugs, finding
520appropriate options for the Makefile and passing on extension code and
521suggestions.  As I am sure to leave someone out, I shall not name anyone else.
522
523Version 1.0 - October 1996.
524Version 1.1 - November 1996 - mainly portability improvements.
525Version 1.2 - January 1997 - mainly drift handling, but much reorganisation.
526Version 1.3 - February 1997 - daemon save file, and some robustness changes.
527Version 1.4 - May 1997 - relatively minor fixes, more diagnostic levels etc.
528Version 1.5 - December 1997 - some very minor fixes
529Version 1.6 - October 2000 - quite a few miscellaneous changes
530
531
532Nick Maclaren,
533University of Cambridge Computer Laboratory,
534New Museums Site, Pembroke Street, Cambridge CB2 3QG, England.
535Email:  nmm1@cam.ac.uk
536Tel.:  +44 1223 334761    Fax:  +44 1223 334679