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 537