PageRenderTime 81ms CodeModel.GetById 43ms app.highlight 15ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/ntp/html/notes.html

https://bitbucket.org/freebsd/freebsd-head/
HTML | 280 lines | 252 code | 28 blank | 0 comment | 0 complexity | ea136623ef648dfec15713bb19cc77e5 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

  1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2
  3<html>
  4
  5	<head>
  6		<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
  7		<meta name="generator" content="HTML Tidy, see www.w3.org">
  8		<title>Notes on setting up a NTP subnet</title>
  9		<link href="scripts/style.css" type="text/css" rel="stylesheet">
 10	</head>
 11
 12	<body>
 13		<h3>Notes on setting up a NTP subnet</h3>
 14		<img src="pic/tonea.gif" alt="gif" align="left">From NBS Special Publication 432 (out of print)
 15		<p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:44</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p>
 16		<br clear="left">
 17		<hr>
 18		<h4>Introduction</h4>
 19		<p>This document is a collection of notes concerning the use of ntpd and related programs, and on coping with the Network Time Protocol (NTP) in general. It is a major rewrite and update of an earlier document written by Dennis Ferguson of the University of Toronto and includes many changes and additions resulting from the NTP Version 3 specification and new Version 4 implementation features. It supersedes earlier documents, which should no longer be used for new configurations.</p>
 20		<p><tt>ntpd</tt> includes a complete implementation of the NTP Version 3 specification, as defined in:</p>
 21		<ul>
 22			<li>Mills, D.L. Network Time Protocol (Version 3) specification, implementation and analysis. Network Working Group Report RFC-1305, University of Delaware, March 1992, 113 pp. Abstract: <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305a.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305a.pdf">PDF</a>, Body: <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305b.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305b.pdf">PDF</a>, Appendices: <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305c.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305c.pdf">PDF</a>
 23		</ul>
 24		<p>Additional features have are described for <a href="release.html">NTP Version 4 Release Notes</a>. It also retains compatibility with both NTP Version 2, as defined in RFC-1119, and NTP Version 1, as defined in RFC-1059, although this compatibility is sometimes strained and only semiautomatic. In order to support in principle the ultimate precision of about 232 picoseconds in the NTP specification, <tt>ntpd</tt> uses NTP timestamp format for external communication and double precision floating point arithmetic internally. <tt>ntpd</tt> fully implements NTP Versions 2 and 3 authentication and in addition Version 4 autokey. It supports the NTP mode-6 control message facility along with a private mode-7 control- message facility used to remotely reconfigure the system and monitor a considerable amount of internal detail. As extensions to the specification, a flexible address-and-mask restriction facility has been included.</p>
 25		<p>The code is biased towards the needs of a busy time server with numerous, often hundreds, of clients and other servers. Tables are hashed to allow efficient handling of many associations, though at the expense of additional overhead when the number of associations is small. Many fancy features have been included to permit efficient management and monitoring of a busy primary server, features which are probably excess baggage for a high stratum client. In such cases, a stripped-down version of the protocol, the Simple Network Time Protocol (SNTP) can be used. SNTP and NTP servers and clients can interwork in most situations, as described in: Mills, D.L. Simple Network Time Protocol (SNTP). Network Working Group Report RFC-2030, University of Delaware, October 1996, 14 pp. <a href="http://www.eecis.udel.edu/%7emills/database/rfc2030.txt">(ASCII)</a>.</p>
 26		<p>The code was written with near demonic attention to details which can affect precision and as a consequence should be able to make good use of high performance, special purpose hardware such as precision oscillators and radio clocks. The present code supports a number of radio clocks, including those for the WWV, CHU, WWVB, MSF, DCF77, GOES and GPS radio and satellite time services and USNO, ACTS and PTB modem time services. It also supports the IRIG-B and IRIG-E signal format connected via an audio codec. The server methodically avoids the use of Unix-specific library routines where possible by implementing local versions, in order to aid in porting the code to perverse Unix and non-Unix platforms.</p>
 27		<p>While this implementation conforms in most respects to the NTP Version 3 specification RFC-1305, a number of improvements have been made which are described in the conformance statement in the <a href="http://www.eecis.udel.edu/%7emills/biblio.html">NTP Protocol Conformance Statement</a> page. It has been specifically tuned to achieve the highest accuracy possible on whatever hardware and operating-system platform is available. In general, its precision and stability are limited only by the characteristics of the onboard clock source used by the hardware and operating system, usually an uncompensated crystal oscillator. On modern RISC-based processors connected directly to radio clocks via serial-asynchronous interfaces, the accuracy is usually limited by the radio clock and interface to the order of a millisecond or less. The code includes special features to support a pulse-per-second (PPS) signal and/or an IRIG-B signal generated by some radio clocks. When used in conjunction with a suitable hardware level converter, the accuracy can be improved to a few tens of microseconds. Further improvement is possible using an outboard, stabilized frequency source, in which the accuracy and stability are limited only by the characteristics of that source.</p>
 28		<p>The NTP Version 4 distribution includes, in addition to the daemon itself (<tt><a href="ntpd.html">ntpd</a></tt>), several utility programs, including two remote-monitoring programs (<a href="ntpq.html"><tt>ntpq</tt></a>, <tt><a href="ntpdc.html">ntpdc</a></tt>), a remote clock-setting program similar to the Unix rdate program (<tt>ntpdate</tt>), a traceback utility useful to discover suitable synchronization sources (<tt>ntptrace</tt>), and various programs used to configure the local platform and calibrate the intrinsic errors. NTP has been ported to a large number of platforms, including most RISC and CISC workstations and mainframes manufactured today. Example configuration files for many models of these machines are included in the distribution. While in most cases the standard version of the implementation runs with no hardware or operating system modifications, not all features of the distribution are available on all platforms. For instance, a special feature allowing Sun workstations to achieve accuracies in the order of 100 microseconds requires some minor changes and additions to the kernel and input/output support.</p>
 29		<p>There are, however, several drawbacks to all of this. <tt>ntpd</tt> is quite fat. This is rotten if your intended platform for the daemon is memory limited. <tt>ntpd</tt> uses <tt>SIGIO</tt> for all input, a facility which appears to not enjoy universal support and whose use seems to exercise the parts of your vendors' kernels which are most likely to have been done poorly. The code is unforgiving in the face of kernel problems which affect performance, and generally requires that you repair the problems in order to achieve acceptable performance. The code has a distinctly experimental flavour and contains features which could charitably be termed failed experiments, but which have not been completely hacked out. Much was learned from the addition of support for a variety of radio clocks, with the result that some radio clock drivers could use some rewriting.</p>
 30		<h4>How NTP Works</h4>
 31		<p>The approach used by NTP to achieve reliable time synchronization from a set of possibly unreliable remote time servers is somewhat different than other protocols. In particular, NTP does not attempt to synchronize clocks to each other. Rather, each server attempts to synchronize to Universal Coordinated Time (UTC) using the best available source and available transmission paths to that source. This is a fine point which is worth understanding. A group of NTP-synchronized clocks may be close to each other in time, but this is not a consequence of the clocks in the group having synchronized to each other, but rather because each clock has synchronized closely to UTC via the best source it has access to. As such, trying to synchronize a set of clocks to a set of servers whose time is not in mutual agreement may not result in any sort of useful synchronization of the clocks, even if you don't care about UTC. However, in networks isolated from UTC sources, provisions can made to nominate one of them as a phantom UTC source.</p>
 32		<p>NTP operates on the premise that there is one true standard time, and that if several servers which claim synchronization to standard time disagree about what that time is, then one or more of them must be broken. There is no attempt to resolve differences more gracefully since the premise is that substantial differences cannot exist. In essence, NTP expects that the time being distributed from the root of the synchronization subnet will be derived from some external source of UTC (e.g., a radio clock). This makes it somewhat inconvenient (though by no means impossible) to synchronize hosts together without a reliable source of UTC to synchronize them to. If your network is isolated and you cannot access other people's servers across the Internet, a radio clock may make a good investment.</p>
 33		<p>Time is distributed through a hierarchy of NTP servers, with each server adopting a <i>stratum</i> which indicates how far away from an external source of UTC it is operating at. Stratum-1 servers, which are at the top of the pile (or bottom, depending on your point of view), have access to some external time source, usually a radio clock synchronized to time signal broadcasts from radio stations which explicitly provide a standard time service. A stratum-2 server is one which is currently obtaining time from a stratum-1 server, a stratum-3 server gets its time from a stratum-2 server, and so on. To avoid long lived synchronization loops the number of strata is limited to 15.</p>
 34		<p>Each client in the synchronization subnet (which may also be a server for other, higher stratum clients) chooses exactly one of the available servers to synchronize to, usually from among the lowest stratum servers it has access to. This is, however, not always an optimal configuration, for indeed NTP operates under another premise as well, that each server's time should be viewed with a certain amount of distrust. NTP really prefers to have access to several sources of lower stratum time (at least three) since it can then apply an agreement algorithm to detect insanity on the part of any one of these. Normally, when all servers are in agreement, NTP will choose the best of these, where &quot;best&quot; is defined in terms of lowest stratum, closest (in terms of network delay) and claimed precision, along with several other considerations. The implication is that, while one should aim to provide each client with three or more sources of lower stratum time, several of these will only be providing backup service and may be of lesser quality in terms of network delay and stratum (i.e., a same-stratum peer which receives time from lower stratum sources the local server doesn't access directly can also provide good backup service).</p>
 35		<p>Finally, there is the issue of association modes. There are a number of modes in which NTP servers can associate with each other, with the mode of each server in the pair indicating the behaviour the other server can expect from it. In particular, when configuring a server to obtain time from other servers, there is a choice of two modes which may be used. Configuring an association in symmetric-active mode (usually indicated by a <tt>peer</tt> declaration in the configuration file) indicates to the remote server that one wishes to obtain time from the remote server and that one is also willing to supply time to the remote server if need be. This mode is appropriate in configurations involving a number of redundant time servers interconnected via diverse network paths, which is presently the case for most stratum-1 and stratum-2 servers on the Internet today. Configuring an association in client mode (usually indicated by a <tt>server</tt> declaration in the configuration file) indicates that one wishes to obtain time from the remote server, but that one is not willing to provide time to the remote server. This mode is appropriate for file-server and workstation clients that do not provide synchronization to other local clients. Client mode is also useful for boot-date-setting programs and the like, which really have no time to provide and which don't retain state about associations over the longer term.</p>
 36		<p>Where the requirements in accuracy and reliability are modest, clients can be configured to use broadcast and/or multicast modes. These modes are not normally utilized by servers with dependent clients. The advantage of these modes is that clients do not need to be configured for a specific server, so that all clients operating can use the same configuration file. Broadcast mode requires a broadcast server on the same subnet, while multicast mode requires support for IP multicast on the client machine, as well as connectivity via the MBONE to a multicast server. Since broadcast messages are not propagated by routers, only those broadcast servers on the same subnet will be used. There is at present no way to select which of possibly many multicast servers will be used, since all operate on the same group address.</p>
 37		<p>Where the maximum accuracy and reliability provided by NTP are needed, clients and servers operate in either client/server or symmetric modes. Symmetric modes are most often used between two or more servers operating as a mutually redundant group. In these modes, the servers in the group members arrange the synchronization paths for maximum performance, depending on network jitter and propagation delay. If one or more of the group members fail, the remaining members automatically reconfigure as required. Dependent clients and servers normally operate in client/server mode, in which a client or dependent server can be synchronized to a group member, but no group member can synchronize to the client or dependent server. This provides protection against malfunctions or protocol attacks.</p>
 38		<p>Servers that provide synchronization to a sizeable population of clients normally operate as a group of three or more mutually redundant servers, each operating with three or more stratum-one or stratum-two servers in client-server modes, as well as all other members of the group in symmetric modes. This provides protection against malfunctions in which one or more servers fail to operate or provide incorrect time. The NTP algorithms have been specifically engineered to resist attacks where some fraction of the configured synchronization sources accidently or purposely provide incorrect time. In these cases a special voting procedure is used to identify spurious sources and discard their data.</p>
 39		<h4>Configuring Your Subnet</h4>
 40		At startup time the <tt>ntpd</tt> daemon running on a host reads the initial configuration information from a file, usually <tt>/etc/ntp.conf</tt>, unless a different name has been specified at compile time. Putting something in this file which will enable the host to obtain time from somewhere else is usually the first big hurdle after installation of the software itself, which is described in the <a href="build/build.html">Building and Installing the Distribution</a> page. At its simplest, what you need to do in the configuration file is declare the servers that the daemon should poll for time synchronization. In principle, no such list is needed if some other time server operating in broadcast/multicast mode is available, which requires the client to operate in a broadcastclient mode.
 41		<p>In the case of a workstation operating in an enterprise network for a public or private organization, there is often an administrative department that coordinates network services, including NTP. Where available, the addresses of appropriate servers can be provided by that department. However, if this infrastructure is not available, it is necessary to explore some portion of the existing NTP subnet now running in the Internet. There are at present many thousands of time servers running NTP in the Internet, a significant number of which are willing to provide a public time- synchronization service. Some of these are listed in the list of public time servers, which can be accessed via the <a href="http://www.eecis.udel.edu/%7entp">NTP web page</a>. These data are updated on a regular basis using information provided voluntarily by various site administrators. There are other ways to explore the nearby subnet using the <tt><a href="ntptrace.html">ntptrace</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> programs.</p>
 42		<p>It is vital to carefully consider the issues of robustness and reliability when selecting the sources of synchronization. Normally, not less than three sources should be available, preferably selected to avoid common points of failure. It is usually better to choose sources which are likely to be &quot;close&quot; to you in terms of network topology, though you shouldn't worry overly about this if you are unable to determine who is close and who isn't. Normally, it is much more serious when a server becomes faulty and delivers incorrect time than when it simply stops operating, since an NTP-synchronized host normally can coast for hours or even days without its clock accumulating serious error approaching a second, for instance. Selecting at least three sources from different operating administrations, where possible, is the minimum recommended, although a lesser number could provide acceptable service with a degraded degree of robustness.</p>
 43		<p>Normally, it is not considered good practice for a single workstation to request synchronization from a primary (stratum-1) time server. At present, these servers provide synchronization for hundreds of clients in many cases and could, along with the network access paths, become seriously overloaded if large numbers of workstation clients requested synchronization directly. Therefore, workstations located in sparsely populated administrative domains with no local synchronization infrastructure should request synchronization from nearby stratum-2 servers instead. In most cases the keepers of those servers in the lists of public servers provide unrestricted access without prior permission; however, in all cases it is considered polite to notify the administrator listed in the file upon commencement of regular service. In all cases the access mode and notification requirements listed in the file must be respected. Under no conditions should servers not in these lists be used without prior permission, as to do so can create severe problems in the local infrastructure, especially in cases of dial-up access to the Internet.</p>
 44		<p>In the case of a gateway or file server providing service to a significant number of workstations or file servers in an enterprise network it is even more important to provide multiple, redundant sources of synchronization and multiple, diversity-routed, network access paths. The preferred configuration is at least three administratively coordinated time servers providing service throughout the administrative domain including campus networks and subnetworks. Each of these should obtain service from at least two different outside sources of synchronization, preferably via different gateways and access paths. These sources should all operate at the same stratum level, which is one less than the stratum level to be used by the local time servers themselves. In addition, each of these time servers should peer with all of the other time servers in the local administrative domain at the stratum level used by the local time servers, as well as at least one (different) outside source at this level. This configuration results in the use of six outside sources at a lower stratum level (toward the primary source of synchronization, usually a radio clock), plus three outside sources at the same stratum level, for a total of nine outside sources of synchronization. While this may seem excessive, the actual load on network resources is minimal, since the interval between polling messages exchanged between peers usually ratchets back to no more than one message every 17 minutes.</p>
 45		<p>The stratum level to be used by the local time servers is an engineering choice. As a matter of policy, and in order to reduce the load on the primary servers, it is desirable to use the highest stratum consistent with reliable, accurate time synchronization throughout the administrative domain. In the case of enterprise networks serving hundreds or thousands of client file servers and workstations, conventional practice is to obtain service from stratum-1 primary servers listed for public access. When choosing sources away from the primary sources, the particular synchronization path in use at any time can be verified using the <tt>ntptrace</tt> program included in this distribution. It is important to avoid loops and possible common points of failure when selecting these sources. Note that, while NTP detects and rejects loops involving neighboring servers, it does not detect loops involving intervening servers. In the unlikely case that all primary sources of synchronization are lost throughout the subnet, the remaining servers on that subnet can form temporary loops and, if the loss continues for an interval of many hours, the servers will drop off the subnet and free-run with respect to their internal (disciplined) timing sources. After some period with no outside timing source (currently one day), a host will declare itself unsynchronized and provide this information to local application programs.</p>
 46		<p>In many cases the purchase of one or more radio clocks is justified, in which cases good engineering practice is to use the configurations described above anyway and connect the radio clock to one of the local servers. This server is then encouraged to participate in a special primary-server subnetwork in which each radio-equipped server peers with several other similarly equipped servers. In this way the radio-equipped server may provide synchronization, as well as receive synchronization, should the local or remote radio clock(s) fail or become faulty. <tt>ntpd</tt> treats attached radio clock(s) in the same way as other servers and applies the same criteria and algorithms to the time indications, so can detect when the radio fails or becomes faulty and switch to alternate sources of synchronization. It is strongly advised, and in practice for most primary servers today, to employ the authentication or access-control features of the NTP specification in order to protect against hostile intruders and possible destabilization of the time service. Using this or similar strategies, the remaining hosts in the same administrative domain can be synchronized to the three (or more) selected time servers. Assuming these servers are synchronized directly to stratum-1 sources and operate normally as stratum-2, the next level away from the primary source of synchronization, for instance various campus file servers, will operate at stratum 3 and dependent workstations at stratum 4. Engineered correctly, such a subnet will survive all but the most exotic failures or even hostile penetrations of the various, distributed timekeeping resources.</p>
 47		<p>The above arrangement should provide very good, robust time service with a minimum of traffic to distant servers and with manageable loads on the local servers. While it is theoretically possible to extend the synchronization subnet to even higher strata, this is seldom justified and can make the maintenance of configuration files unmanageable. Serving time to a higher stratum peer is very inexpensive in terms of the load on the lower stratum server if the latter is located on the same concatenated LAN. When justified by the accuracy expectations, NTP can be operated in broadcast and multicast modes, so that clients need only listen for periodic broadcasts and do not need to send anything.</p>
 48		<p>When planning your network you might, beyond this, keep in mind a few generic don'ts, in particular:</p>
 49		<ul>
 50			<li>Don't synchronize a local time server to another peer at the same stratum, unless the latter is receiving time from lower stratum sources the former doesn't talk to directly. This minimizes the occurrence of common points of failure, but does not eliminate them in cases where the usual chain of associations to the primary sources of synchronization are disrupted due to failures.
 51			<li style="list-style: none"><br>
 52			<li>Don't configure peer associations with higher stratum servers. Let the higher strata configure lower stratum servers, but not the reverse. This greatly simplifies configuration file maintenance, since there is usually much greater configuration churn in the high stratum clients such as personal workstations.
 53			<li style="list-style: none"><br>
 54			<li>Don't synchronize more than one time server in a particular administrative domain to the same time server outside that domain. Such a practice invites common points of failure, as well as raises the possibility of massive abuse, should the configuration file be automatically distributed do a large number of clients.
 55		</ul>
 56		There are many useful exceptions to these rules. When in doubt, however, follow them.
 57		<h4>Configuring Your Server or Client</h4>
 58		<p>As mentioned previously, the configuration file is usually called /etc/ntp.conf. This is an ASCII file conforming to the usual comment and whitespace conventions. A working configuration file might look like (in this and other examples, do not copy this directly):</p>
 59		<pre>
 60     # peer configuration for host whimsy
 61     # (expected to operate at stratum 2)
 62
 63     server rackety.udel.edu
 64     server umd1.umd.edu
 65     server lilben.tn.cornell.edu
 66
 67     driftfile /etc/ntp.drift
 68</pre>
 69		(Note the use of host names, although host addresses in dotted-quad notation can also be used. It is always preferable to use names rather than addresses, since over time the addresses can change, while the names seldom change.)
 70		<p>This particular host is expected to operate as a client at stratum 2 by virtue of the <tt>server</tt> keyword and the fact that two of the three servers declared (the first two) have radio clocks and usually run at stratum 1. The third server in the list has no radio clock, but is known to maintain associations with a number of stratum 1 peers and usually operates at stratum 2. Of particular importance with the last host is that it maintains associations with peers besides the two stratum 1 peers mentioned. This can be verified using the <tt>ntpq</tt> program mentioned above. When configured using the <tt>server</tt> keyword, this host can receive synchronization from any of the listed servers, but can never provide synchronization to them.</p>
 71		<p>Unless restricted using facilities described later, this host can provide synchronization to dependent clients, which do not have to be listed in the configuration file. Associations maintained for these clients are transitory and result in no persistent state in the host. These clients are normally not visible using the <tt>ntpq</tt> program included in the distribution; however, <tt>ntpd</tt> includes a monitoring feature (described later) which caches a minimal amount of client information useful for debugging administrative purposes.</p>
 72		<p>A time server expected to both receive synchronization from another server, as well as to provide synchronization to it, is declared using the <tt>peer</tt> keyword instead of the <tt>server</tt> keyword. In all other aspects the server operates the same in either mode and can provide synchronization to dependent clients or other peers. If a local source of UTC time is available, it is considered good engineering practice to declare time servers outside the administrative domain as <tt>peer</tt> and those inside as <tt>server</tt> in order to provide redundancy in the global Internet, while minimizing the possibility of instability within the domain itself. A time server in one domain can in principle heal another domain temporarily isolated from all other sources of synchronization. However, it is probably unwise for a casual workstation to bridge fragments of the local domain which have become temporarily isolated.</p>
 73		<p>Note the inclusion of a <tt>driftfile</tt> declaration. One of the things the NTP daemon does when it is first started is to compute the error in the intrinsic frequency of the clock on the computer it is running on. It usually takes about a day or so after the daemon is started to compute a good estimate of this (and it needs a good estimate to synchronize closely to its server). Once the initial value is computed, it will change only by relatively small amounts during the course of continued operation. The <tt>driftfile</tt> declaration indicates to the daemon the name of a file where it may store the current value of the frequency error so that, if the daemon is stopped and restarted, it can reinitialize itself to the previous estimate and avoid the day's worth of time it will take to recompute the frequency estimate. Since this is a desirable feature, a <tt>driftfile</tt> declaration should always be included in the configuration file.</p>
 74		<p>An implication in the above is that, should <tt>ntpd</tt> be stopped for some reason, the local platform time will diverge from UTC by an amount that depends on the intrinsic error of the clock oscillator and the time since last synchronized. In view of the length of time necessary to refine the frequency estimate, every effort should be made to operate the daemon on a continuous basis and minimize the intervals when for some reason it is not running.</p>
 75		<h4>Configuring NTP with NetInfo</h4>
 76		If NetInfo support is compiled into NTP, you can opt to configure NTP in your NetInfo domain. NTP will look in the NetInfo directory <tt>/locations/ntp</tt> for property/value pairs which are equivalent to the lines in the configuration file described above. Each configuration keyword may have a corresponding property in NetInfo. Each value for a given property is treated as arguments to that property, similar to a line in the configuration file.
 77		<p>For example, the configuration shown in the configuration file above can be duplicated in NetInfo by adding a property &quot;<tt>server</tt>&quot; with values &quot;<tt>rackety.udel.edu</tt>&quot;, &quot;<tt>umd1.umd.edu</tt>&quot;, and &quot;<tt>lilben.tn.cornell.edu</tt>&quot;; and a property &quot;<tt>driftfile</tt>&quot; with the single value &quot;<tt>/etc/ntp.drift</tt>&quot;.</p>
 78		<p>Values may contain multiple tokens similar to the arguments available in the configuration file. For example, to use <tt>mimsy.mil</tt> as an NTP version 1 time server, you would add a value &quot;<tt>mimsy.mil version 1</tt>&quot; to the &quot;<tt>server</tt>&quot; property.</p>
 79		<h4>Ntp4 Versus Previous Versions</h4>
 80		There are several items of note when dealing with a mixture of <tt>ntp4</tt> and previous distributions of NTP Version 2 (<tt>ntpd</tt>) and NTP Version 1 (<tt>ntp3.4</tt>). The <tt>ntp4</tt> implementation conforms to the NTP Version 3 specification RFC-1305 and, in addition, contains additional features documented in the <a href="release.html">Release Notes</a> page. As such, by default when no additional information is available concerning the preferences of the peer, <tt>ntpd</tt> claims to be version 4 in the packets that it sends from configured associations. The <tt>version</tt> subcommand of the <tt>server</tt>, <tt>peer</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> command can be used to change the default. In unconfigured (ephemeral) associaitons, the daemon always replies in the same version as the request.
 81		<p>An NTP implementation conforming to a previous version specification ordinarily discards packets from a later version. However, in most respects documented in RFC-1305, The version 2 implementation is compatible with the version 3 algorithms and protocol. The version 1 implementation contains most of the version 2 algorithms, but without important features for clock selection and robustness. Nevertheless, in most respects the NTP versions are backwards compatible. The sticky part here is that, when a previous version implementation receives a packet claiming to be from a version 4 server, it discards it without further processing. Hence there is a danger that in some situations synchronization with previous versions will fail.</p>
 82		<p>The trouble occurs when an previous version is to be included in an <tt>ntpd</tt> configuration file. With no further indication, <tt>ntpd</tt> will send packets claiming to be version 4 when it polls. To get around this, <tt>ntpd</tt> allows a qualifier to be added to configuration entries to indicate which version to use when polling. Hence the entries</p>
 83		<pre>
 84     # specify NTP version 1
 85
 86     server mimsy.mil version
 871     # server running ntpd version 1
 88     server apple.com version
 892     # server running ntpd version 2
 90</pre>
 91		will cause version 1 packets to be sent to the host mimsy.mil and version 2 packets to be sent to apple.com. If you are testing <tt>ntpd</tt> against previous version servers you will need to be careful about this. Note that, as indicated in the RFC-1305 specification, there is no longer support for the original NTP specification, once called NTP Version 0.
 92		<h4>Traffic Monitoring</h4>
 93		<tt>ntpd</tt> handles peers whose stratum is higher than the stratum of the local server and polls using client mode by a fast path which minimizes the work done in responding to their polls, and normally retains no memory of these pollers. Sometimes, however, it is interesting to be able to determine who is polling the server, and how often, as well as who has been sending other types of queries to the server.
 94		<p>To allow this, <tt>ntpd</tt> implements a traffic monitoring facility which records the source address and a minimal amount of other information from each packet which is received by the server. This feature is normally enabled, but can be disabled if desired using the configuration file entry:</p>
 95		<pre>
 96     # disable monitoring feature
 97     disable monitor
 98</pre>
 99		The recorded information can be displayed using the <tt>ntpdc</tt> query program, described briefly below.
100		<h4>Address-and-Mask Restrictions</h4>
101		The address-and-mask configuration facility supported by <tt>ntpd</tt> is quite flexible and general, but is not an integral part of the NTP Version 3 specification. The major drawback is that, while the internal implementation is very nice, the user interface is not. For this reason it is probably worth doing an example here. Briefly, the facility works as follows. There is an internal list, each entry of which holds an address, a mask and a set of flags. On receipt of a packet, the source address of the packet is compared to each entry in the list, with a match being posted when the following is true:
102		<pre>
103     (source_addr &amp; mask) == (address &amp;
104mask)
105</pre>
106		A particular source address may match several list entries. In this case the entry with the most one bits in the mask is chosen. The flags associated with this entry are used to control the access.
107		<p>In the current implementation the flags always add restrictions. In effect, an entry with no flags set leaves matching hosts unrestricted. An entry can be added to the internal list using a <tt>restrict</tt> declaration. The flags associated with the entry are specified textually. For example, the <tt>notrust</tt> flag indicates that hosts matching this entry, while treated normally in other respects, shouldn't be trusted to provide synchronization even if otherwise so enabled. The <tt>nomodify</tt> flag indicates that hosts matching this entry should not be allowed to do run-time configuration. There are many more flags, see the <a href="ntpd.html"><tt>ntpd</tt></a> page.</p>
108		<p>Now the example. Suppose you are running the server on a host whose address is 128.100.100.7. You would like to ensure that run time reconfiguration requests can only be made from the local host and that the server only ever synchronizes to one of a pair of off-campus servers or, failing that, a time source on net 128.100. The following entries in the configuration file would implement this policy:</p>
109		<pre>
110     # by default, don't trust and don't allow
111modifications
112
113     restrict default notrust nomodify
114
115     # these guys are trusted for time, but no
116modifications allowed
117
118     restrict 128.100.0.0 mask 255.255.0.0 nomodify
119     restrict 128.8.10.1 nomodify
120     restrict 192.35.82.50 nomodify
121
122     # the local addresses are unrestricted
123
124     restrict 128.100.100.7
125     restrict 127.0.0.1
126</pre>
127		The first entry is the default entry, which all hosts match and hence which provides the default set of flags. The next three entries indicate that matching hosts will only have the <tt>nomodify</tt> flag set and hence will be trusted for time. If the mask isn't specified in the <tt>restrict</tt> keyword, it defaults to 255.255.255.255. Note that the address 128.100.100.7 matches three entries in the table, the default entry (mask 0.0.0.0), the entry for net 128.100 (mask 255.255.0.0) and the entry for the host itself (mask 255.255.255.255). As expected, the flags for the host are derived from the last entry since the mask has the most bits set.
128		<p>The only other thing worth mentioning is that the <tt>restrict</tt> declarations apply to packets from all hosts, including those that are configured elsewhere in the configuration file and even including your clock pseudopeer(s), if any. Hence, if you specify a default set of restrictions which you don't wish to be applied to your configured peers, you must remove those restrictions for the configured peers with additional <tt>restrict</tt> declarations mentioning each peer separately.</p>
129		<h4>Authentication</h4>
130		<tt>ntpd</tt> supports the optional authentication procedure specified in the NTP Version 2 and 3 specifications. Briefly, when an association runs in authenticated mode, each packet transmitted has appended to it a 32-bit key ID and a 64/128-bit cryptographic checksum of the packet contents computed using either the Data Encryption Standard (DES) or Message Digest (MD5) algorithms. Note that, while either of these algorithms provide sufficient protection from message- modification attacks, distribution of the former algorithm implementation is restricted to the U.S. and Canada, while the latter presently is free from such restrictions. For this reason, the DES algorithm is not included in the current distribution. Directions for obtaining it in other countries is in the <a href="build/build.html">Building and Installing the Distribution</a> page. With either algorithm the receiving peer recomputes the checksum and compares it with the one included in the packet. For this to work, the peers must share at least one encryption key and, furthermore, must associate the shared key with the same key ID.
131		<p>This facility requires some minor modifications to the basic packet processing procedures, as required by the specification. These modifications are enabled by the <tt>enable auth</tt> configuration declaration, which is currently the default. In authenticated mode, peers which send unauthenticated packets, peers which send authenticated packets which the local server is unable to decrypt and peers which send authenticated packets encrypted using a key we don't trust are all marked untrustworthy and unsuitable for synchronization. Note that, while the server may know many keys (identified by many key IDs), it is possible to declare only a subset of these as trusted. This allows the server to share keys with a client which requires authenticated time and which trusts the server, but which is not trusted by the server. Also, some additional configuration language is required to specify the key ID to be used to authenticate each configured peer association. Hence, for a server running in authenticated mode, the configuration file might look similar to the following:</p>
132		<pre>
133     # peer configuration for 128.100.100.7
134     # (expected to operate at stratum 2)
135     # fully authenticated this time
136
137     peer 128.100.49.105 key 22 #
138suzuki.ccie.utoronto.ca
139     peer 128.8.10.1 key 4    #
140umd1.umd.edu
141     peer 192.35.82.50 key 6  #
142lilben.tn.cornell.edu
143
144     keys /usr/local/etc/ntp.keys  # path for
145key file
146     trustedkey 1 2 14 15     #
147define trusted keys
148     requestkey
14915            #
150key (7) for accessing server variables
151     controlkey
15215            #
153key (6) for accessing server variables
154
155     authdelay
1560.000094       # authentication delay
157(Sun4c/50 IPX)
158</pre>
159		There are a couple of previously unmentioned things in here. The <tt>keys</tt> line specifies the path to the keys file (see below and the <tt>ntpd</tt> document page for details of the file format). The <tt>trustedkey</tt> declaration identifies those keys that are known to be uncompromised; the remainder presumably represent the expired or possibly compromised keys. Both sets of keys must be declared by key identifier in the <tt>ntp.keys</tt> file described below. This provides a way to retire old keys while minimizing the frequency of delicate key-distribution procedures. The <tt>requestkey</tt> line establishes the key to be used for mode-6 control messages as specified in RFC-1305 and used by the <tt>ntpq</tt> utility program, while the <tt>controlkey</tt> line establishes the key to be used for mode-7 private control messages used by the <tt>ntpdc</tt> utility program. These keys are used to prevent unauthorized modification of daemon variables.
160		<p>Ordinarily, the authentication delay; that is, the processing time taken between the freezing of a transmit timestamp and the actual transmission of the packet when authentication is enabled (i.e. more or less the time it takes for the DES or MD5 routine to encrypt a single block) is computed automatically by the daemon. If necessary, the delay can be overridden by the <tt>authdelay</tt> line, which is used as a correction for the transmit timestamp.</p>
161		Additional utility programs included in the <tt>./authstuff</tt> directory can be used to generate random keys, certify implementation correctness and display sample keys. As a general rule, keys should be chosen randomly, except possibly the request and control keys, which must be entered by the user as a password.
162		<p>The <tt>ntp.keys</tt> file contains the list of keys and associated key IDs the server knows about (for obvious reasons this file is better left unreadable by anyone except root). The contents of this file might look like:</p>
163		<pre>
164     # ntp keys file (ntp.keys)
165     1    N   
16629233E0461ECD6AE    # DES key in NTP format
167     2    M   
168RIrop8KPPvQvYotM    # md5 key as an ASCII random string
169     14   M   
170sundial           
171;  # md5 key as an ASCII string
172     15   A   
173sundial           
174;  # DES key as an ASCII string
175
176     # the following 3 keys are identical
177
178     10   A    SeCReT
179     10   N   
180d3e54352e5548080
181     10   S   
182a7cb86a4cba80101
183</pre>
184		In the keys file the first token on each line indicates the key ID, the second token the format of the key and the third the key itself. There are four key formats. An <tt>A</tt> indicates a DES key written as a 1- to-8 character string in 7-bit ASCII representation, with each character standing for a key octet (like a Unix password). An <tt>S</tt> indicates a DES key written as a hex number in the DES standard format, with the low order bit (LSB) of each octet being the (odd) parity bit. An <tt>N</tt> indicates a DES key again written as a hex number, but in NTP standard format with the high order bit of each octet being the (odd) parity bit (confusing enough?). An <tt>M</tt> indicates an MD5 key written as a 1-to-31 character ASCII string in the <tt>A</tt> format. Note that, because of the simple tokenizing routine, the characters <tt>' ', '#', '\t', '\n'</tt> and <tt>'\0'</tt> can't be used in either a DES or MD5 ASCII key. Everything else is fair game, though. Key 0 (zero) is used for special purposes and should not appear in this file.
185		<p>The big trouble with the authentication facility is the keys file. It is a maintenance headache and a security problem. This should be fixed some day. Presumably, this whole bag of worms goes away if/when a generic security regime for the Internet is established. An alternative with NTP Version 4 is the autokey feature, which uses random session keys and public-key cryptography and avoids the key file entirely. While this feature is not completely finished yet, details can be found in the <a href="release.html">Release Notes</a> page.</p>
186		<h4>Query Programs</h4>
187		Three utility query programs are included with the distribution, <tt>ntpq</tt>, <tt>ntptrace</tt> and <tt>ntpdc</tt>. <tt>ntpq</tt> is a handy program which sends queries and receives responses using NTP standard mode-6 control messages. Since it uses the standard control protocol specified in RFC- 1305, it may be used with NTP Version 2 and Version 3 implementations for both Unix and Fuzzball, but not Version 1 implementations. It is most useful to query remote NTP implementations to assess timekeeping accuracy and expose bugs in configuration or operation.
188		<p><tt>ntptrace</tt> can be used to display the current synchronization path from a selected host through possibly intervening servers to the primary source of synchronization, usually a radio clock. It works with both version 2 and version 3 servers, but not version 1.</p>
189		<p><tt>ntpdc</tt> is a horrid program which uses NTP private mode-7 control messages to query local or remote servers. The format and contents of these messages are specific to this version of <tt>ntpd</tt> and some older versions. The program does allow inspection of a wide variety of internal counters and other state data, and hence does make a pretty good debugging tool, even if it is frustrating to use. The other thing of note about <tt>ntpdc</tt> is that it provides a user interface to the run time reconfiguration facility. See the respective document pages for details on the use of these programs.</p>
190		<h4>Run-Time Reconfiguration</h4>
191		<tt>ntpd</tt> was written specifically to allow its configuration to be fully modifiable at run time. Indeed, the only way to configure the server is at run time. The configuration file is read only after the rest of the server has been initialized into a running default-configured state. This facility was included not so much for the benefit of Unix, where it is handy but not strictly essential, but rather for dedicated platforms where the feature is more important for maintenance. Nevertheless, run time configuration works very nicely for Unix servers as well.
192		<p>Nearly all of the things it is possible to configure in the configuration file may be altered via NTP mode-7 messages using the <tt>ntpdc</tt> program. Mode-6 messages may also provide some limited configuration functionality (though the only thing you can currently do with mode-6 messages is set the leap-second warning bits) and the <tt>ntpq</tt> program provides generic support for the latter. The leap bits that can be set in the <tt>leap_warning</tt> variable (up to one month ahead) and in the <tt>leap_indication</tt> variable have a slightly different encoding than the usual interpretation:</p>
193		<pre>
194       
195Value           Action
196
197        
19800            
199p; The daemon passes the leap bits of its
200            
201           
202synchronisation source (usual mode of operation)
203
204        01/10   A leap
205second is added/deleted
206
207        
20811            
209p; Leap information from the synchronization source
210            
211            is
212ignored (thus LEAP_NOWARNING is passed on)
213</pre>
214		Mode-6 and mode-7 messages which would modify the configuration of the server are required to be authenticated using standard NTP authentication. To enable the facilities one must, in addition to specifying the location of a keys file, indicate in the configuration file the key IDs to be used for authenticating reconfiguration commands. Hence the following fragment might be added to a configuration file to enable the mode-6 (ntpq) and mode-7 (ntpdc) facilities in the daemon:
215		<pre>
216     # specify mode-6 and mode-7 trusted keys
217
218     requestkey 65535    # for mode-7
219requests
220     controlkey 65534    # for mode-6
221requests
222</pre>
223		If the <tt>requestkey</tt> and/or the <tt>controlkey</tt> configuration declarations are omitted from the configuration file, the corresponding run-time reconfiguration facility is disabled.
224		<p>The query programs require the user to specify a key ID and a key to use for authenticating requests to be sent. The key ID provided should be the same as the one mentioned in the configuration file, while the key should match that corresponding to the key ID in the keys file. As the query programs …

Large files files are truncated, but you can click here to view the full file