share/doc/smm/11.timedop/timed.ms

   1 .\" Copyright (c) 1986, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)timed.ms    8.1 (Berkeley) 6/8/93
  29 .\"
  30 .TL
  31 Timed Installation and Operation Guide
  32 .AU
  33 Riccardo Gusella, Stefano Zatti, James M. Bloom
  34 .AI
  35 Computer Systems Research Group
  36 Computer Science Division
  37 Department of Electrical Engineering and Computer Science
  38 University of California, Berkeley
  39 Berkeley, CA 94720
  40 .AU
  41 Kirk Smith
  42 .AI
  43 Engineering Computer Network
  44 Department of Electrical Engineering
  45 Purdue University
  46 West Lafayette, IN 47906
  47 .FS
  48 This work was sponsored by the Defense Advanced Research Projects Agency
  49 (DoD), monitored by the Naval Electronics Systems
  50 Command under contract No. N00039-84-C-0089, and by the CSELT
  51 Corporation of Italy.
  52 The views and conclusions contained in this document are those of the
  53 authors and should not be interpreted as representing official policies,
  54 either expressed or implied, of the Defense Research Projects Agency,
  55 of the US Government, or of CSELT.
  56 .FE
  57 .LP
  58 .EH 'SMM:11-%''Timed Installation and Operation'
  59 .OH 'Timed Installation and Operation''SMM:11-%'
  60 .SH
  61 Introduction
  62 .PP
  63 The clock synchronization service for
  64 the UNIX 4.3BSD operating system is composed of a collection of
  65 time daemons (\fItimed\fP) running on the machines in a local
  66 area network.
  67 The algorithms implemented by the service is based on a master-slave scheme.
  68 The time daemons communicate with each other using the
  69 \fITime Synchronization Protocol\fP (TSP) which
  70 is built on the DARPA UDP protocol and described in detail in [4].
  71 .PP
  72 A time daemon has a twofold function.
  73 First, it supports the synchronization of the clocks
  74 of the various hosts in a local area network.
  75 Second, it starts (or takes part in) the election that occurs
  76 among slave time daemons when, for any reason, the master disappears.
  77 The synchronization mechanism and the election procedure
  78 employed by the program \fItimed\fP are described
  79 in other documents [1,2,3].
  80 The next paragraphs are a brief overview of how the time daemon works.
  81 This document is mainly concerned with the administrative and technical
  82 issues of running \fItimed\fP at a particular site.
  83 .PP
  84 A \fImaster time daemon\fP measures the time
  85 differences between the clock of the machine on which it
  86 is running and those of all other machines.
  87 The master computes the \fInetwork time\fP as the average of the
  88 times provided by nonfaulty clocks.\**
  89 .FS
  90 A clock is considered to be faulty when its value
  91 is more than a small specified
  92 interval apart from the majority of the clocks
  93 of the other machines [1,2].
  94 .FE
  95 It then sends to each \fIslave time daemon\fP the
  96 correction that should be performed on the clock of its machine.
  97 This process is repeated periodically.
  98 Since the correction is expressed as a time difference rather than an
  99 absolute time, transmission delays do not interfere with
 100 the accuracy of the synchronization.
 101 When a machine comes up and joins the network,
 102 it starts a slave time daemon which
 103 will ask the master for the correct time and will reset the machine's clock
 104 before any user activity can begin.
 105 The time daemons are able to maintain a single network time in spite of
 106 the drift of clocks away from each other.
 107 The present implementation keeps processor clocks synchronized
 108 within 20 milliseconds.
 109 .PP
 110 To ensure that the service provided is continuous and reliable,
 111 it is necessary to implement an election algorithm to elect a
 112 new master should the machine running the current master crash, the master
 113 terminate (for example, because of a run-time error), or
 114 the network be partitioned.
 115 Under our algorithm, slaves are able to realize when the master has
 116 stopped functioning and to elect a new master from among themselves.
 117 It is important to note that, since the failure of the master results
 118 only in a gradual divergence of clock values, the election
 119 need not occur immediately.
 120 .PP
 121 The machines that are gateways between distinct local area
 122 networks require particular care.
 123 A time daemon on such machines may act as a \fIsubmaster\fP.
 124 This artifact depends on the current inability of
 125 transmission protocols to broadcast a message on a network
 126 other than the one to which the broadcasting machine is connected.
 127 The submaster appears as a slave on one network, and as a master
 128 on one or more of the other networks to which it is connected.
 129 .PP
 130 A submaster classifies each network as one of three types.
 131 A \fIslave network\fP is a network on which the submaster acts as a slave.
 132 There can only be one slave network.
 133 A \fImaster network\fP is a network on which the submaster acts as a master.
 134 An \fIignored network\fP is any other network which already has a valid master.
 135 The submaster tries periodically to become master on an ignored
 136 network, but gives up immediately if a master already exists.
 137 .SH
 138 Guidelines
 139 .PP
 140 While the synchronization algorithm is quite general, the election
 141 one, requiring a broadcast mechanism, puts constraints on
 142 the kind of network on which time daemons can run.
 143 The time daemon will only work on networks with broadcast capability
 144 augmented with point-to-point links.
 145 Machines that are only connected to point-to-point,
 146 non-broadcast networks may not use the time daemon.
 147 .PP
 148 If we exclude submasters, there will normally be, at most, one master time
 149 daemon in a local area internetwork.
 150 During an election, only one of the slave time daemons
 151 will become the new master.
 152 However, because of the characteristics of its machine,
 153 a slave can be prevented from becoming the master.
 154 Therefore, a subset of machines must be designated as potential
 155 master time daemons.
 156 A master time daemon will require CPU resources
 157 proportional to the number of slaves, in general, more than
 158 a slave time daemon, so it may be advisable to limit master time
 159 daemons to machines with more powerful processors or lighter loads.
 160 Also, machines with inaccurate clocks should not be used as masters.
 161 This is a purely administrative decision: an organization may
 162 well allow all of its machines to run master time daemons.
 163 .PP
 164 At the administrative level, a time daemon on a machine
 165 with multiple network interfaces, may be told to ignore all
 166 but one network or to ignore one network.
 167 This is done with the \fI\-n network\fP and \fI\-i network\fP
 168 options respectively at start-up time.
 169 Typically, the time daemon would be instructed to ignore all but
 170 the networks belonging to the local administrative control.
 171 .PP
 172 There are some limitations to the current
 173 implementation of the time daemon.
 174 It is expected that these limitations will be removed in future releases.
 175 The constant NHOSTS in /usr/src/etc/timed/globals.h limits the
 176 maximum number of machines that may be directly controlled by one
 177 master time daemon.
 178 The current maximum is 29 (NHOSTS \- 1).
 179 The constant  must be changed and the program recompiled if a site wishes to
 180 run \fItimed\fP on a larger (inter)network.
 181 .PP
 182 In addition, there is a \fIpathological situation\fP to
 183 be avoided at all costs, that might occur when
 184 time daemons run on multiply-connected local area networks.
 185 In this case, as we have seen, time daemons running on gateway machines
 186 will be submasters and they will act on some of those
 187 networks as master time daemons.
 188 Consider machines A and B that are both gateways between
 189 networks X and Y.
 190 If time daemons were started on both A and B without constraints, it would be
 191 possible for submaster time daemon A to be a slave on network X
 192 and the master on network Y, while submaster time daemon B is a slave on
 193 network Y and the master on network X.
 194 This \fIloop\fP of master time daemons will not function properly
 195 or guarantee a unique time on both networks, and will cause
 196 the submasters to use large amounts of system resources in the form
 197 of network bandwidth and CPU time.
 198 In fact, this kind of \fIloop\fP can also be generated with more
 199 than two master time daemons,
 200 when several local area networks are interconnected.
 201 .SH
 202 Installation
 203 .PP
 204 In order to start the time daemon on a given machine,
 205 the following lines should be
 206 added to the \fIlocal daemons\fP section in the file \fI/etc/rc.local\fP:
 207 .sp 2
 208 .in 1i
 209 .nf
 210 if [ -f /etc/timed ]; then
 211         /etc/timed \fIflags\fP & echo -n ' timed' >/dev/console
 212 fi
 213 .fi
 214 .in -1i
 215 .sp
 216 .LP
 217 In any case, they must appear after the network
 218 is configured via ifconfig(8).
 219 .PP
 220 Also, the file \fI/etc/services\fP should contain the following
 221 line:
 222 .sp 2
 223 .ti 1i
 224 timed           525/udp         timeserver
 225 .sp
 226 .LP
 227 The \fIflags\fP are:
 228 .IP "-n network" 13
 229 to consider the named network.
 230 .IP "-i network"
 231 to ignore the named network.
 232 .IP -t
 233 to place tracing information in \fI/usr/adm/timed.log\fP.
 234 .IP -M
 235 to allow this time daemon to become a master.
 236 A time daemon run without this option will be forced in the state of
 237 slave during an election.
 238 .SH
 239 Daily Operation
 240 .PP
 241 \fITimedc(8)\fP is used to control the operation of the time daemon.
 242 It may be used to:
 243 .IP \(bu
 244 measure the differences between machines' clocks,
 245 .IP \(bu
 246 find the location where the master \fItimed\fP is running,
 247 .IP \(bu
 248 cause election timers on several machines to expire at the same time,
 249 .IP \(bu
 250 enable or  disable  tracing  of  messages  received  by \fItimed\fP.
 251 .LP
 252 See the manual page on \fItimed\fP\|(8) and \fItimedc\fP\|(8)
 253 for more detailed information.
 254 .PP
 255 The \fIdate(1)\fP command can be used to set the network date.
 256 In order to set the time on a single machine, the \fI-n\fP flag
 257 can be given to date(1).
 258 .bp
 259 .SH
 260 References
 261 .IP 1.
 262 R. Gusella and S. Zatti,
 263 \fITEMPO: A Network Time Controller for Distributed Berkeley UNIX System\fP,
 264 USENIX Summer Conference Proceedings, Salt Lake City, June 1984.
 265 .IP 2.
 266 R. Gusella and S. Zatti, \fIClock Synchronization in a Local Area Network\fP,
 267 University of California, Berkeley, Technical Report, \fIto appear\fP.
 268 .IP 3.
 269 R. Gusella and S. Zatti,
 270 \fIAn Election Algorithm for a Distributed Clock Synchronization Program\fP,
 271 University of California, Berkeley, CS Technical Report #275, Dec. 1985.
 272 .IP 4.
 273 R. Gusella and S. Zatti,
 274 \fIThe Berkeley UNIX 4.3BSD Time Synchronization Protocol\fP,
 275 UNIX Programmer's Manual, 4.3 Berkeley Software Distribution, Volume 2c.