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