usr.sbin/timed/timed/timed.8

   1 .\" Copyright (c) 1980, 1991, 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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)timed.8     8.1 (Berkeley) 6/6/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd June 6, 1993
  36 .Dt TIMED 8
  37 .Os
  38 .Sh NAME
  39 .Nm timed
  40 .Nd time server daemon
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl dtM
  44 .Op Fl i Ar network | Fl n Ar network
  45 .Op Fl F Ar host ...
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 utility is a time server daemon
  50 which is normally invoked at boot time from the
  51 .Xr rc.network 8
  52 file.
  53 It synchronizes the host's time with the time of other
  54 machines, which are also running
  55 .Nm ,
  56 in a local area network.
  57 These time servers will slow down the clocks of some machines
  58 and speed up the clocks of others to bring them to the average network time.
  59 The average network time is computed from measurements of clock differences
  60 using the
  61 .Tn ICMP
  62 timestamp request message.
  63 .Pp
  64 The following options are available:
  65 .Bl -tag -width indent
  66 .It Fl d
  67 Enable debugging mode;
  68 do not detach from the terminal.
  69 .It Fl i Ar network
  70 Add
  71 .Ar network
  72 to the list of networks to ignore.
  73 All other networks
  74 to which the machine is directly connected
  75 are used by
  76 .Nm .
  77 This option may be specified multiple times
  78 to add more than one network to the list.
  79 .It Fl F Ar host ...
  80 Create a list of trusted hosts.
  81 The
  82 .Nm
  83 utility will only accept trusted hosts as masters.
  84 If it finds an untrusted host claiming to be master,
  85 .Nm
  86 will suppress incoming messages from that host
  87 and call for a new election.
  88 This option implies the
  89 .Fl M
  90 option.
  91 If this option is not specified,
  92 all hosts on the connected networks are treated as trustworthy.
  93 .It Fl M
  94 Allow this host to become a
  95 .Nm
  96 master if necessary.
  97 .It Fl n Ar network
  98 Add
  99 .Ar network
 100 to the list of allowed networks.
 101 All other networks
 102 to which the machine is directly connected
 103 are ignored by
 104 .Nm .
 105 This option may be specified multiple times
 106 to add more than one network to the list.
 107 .It Fl t
 108 Enable tracing of received messages
 109 and log to the file
 110 .Pa /var/log/timed.log .
 111 Tracing can be turned on or off while
 112 .Nm
 113 is running with the
 114 .Xr timedc 8
 115 utility.
 116 .El
 117 .Pp
 118 The
 119 .Fl n
 120 and
 121 .Fl i
 122 flags are mutually exclusive
 123 and require as arguments real networks to which
 124 the host is connected
 125 (see
 126 .Xr networks 5 ) .
 127 If neither flag is specified,
 128 .Nm
 129 will listen on all connected networks.
 130 .Pp
 131 A
 132 .Nm
 133 running without the
 134 .Fl M
 135 nor
 136 .Fl F
 137 flags will always remain a slave.
 138 If the
 139 .Fl F
 140 flag is not used,
 141 .Nm
 142 will treat all machines as trustworthy.
 143 .Pp
 144 The
 145 .Nm
 146 utility is based on a master-slave
 147 scheme.
 148 When
 149 .Nm
 150 is started on a machine, it asks the master for the network time
 151 and sets the host's clock to that time.
 152 After that, it accepts synchronization messages periodically sent by
 153 the master and calls
 154 .Xr adjtime 2
 155 to perform the needed corrections on the host's clock.
 156 .Pp
 157 It also communicates with
 158 .Xr date 1
 159 in order to set the date globally,
 160 and with
 161 .Xr timedc 8 ,
 162 a
 163 .Nm
 164 control utility.
 165 If the machine running the master becomes unreachable,
 166 the slaves will elect a new master
 167 from among those slaves
 168 which are running with at least one of the
 169 .Fl M
 170 and
 171 .Fl F
 172 flags.
 173 .Pp
 174 At startup
 175 .Nm
 176 normally checks for a master time server on each network to which
 177 it is connected, except as modified by the
 178 .Fl n
 179 and
 180 .Fl i
 181 options described above.
 182 It will request synchronization service from the first master server
 183 located.
 184 If permitted by the
 185 .Fl M
 186 or
 187 .Fl F
 188 flags, it will provide synchronization service on any attached networks
 189 on which no trusted master server was detected.
 190 Such a server propagates the time computed by the top-level master.
 191 The
 192 .Nm
 193 utility will periodically check for the presence of a master
 194 on those networks for which it is operating as a slave.
 195 If it finds that there are no trusted masters on a network,
 196 it will begin the election process on that network.
 197 .Pp
 198 One way to synchronize a group of machines is to use
 199 .Xr ntpd 8
 200 to
 201 synchronize the clock of one machine to a distant standard or a radio
 202 receiver and
 203 .Fl F Ar hostname
 204 to tell its
 205 .Nm
 206 to trust only itself.
 207 .Pp
 208 Messages printed by the kernel on the system console occur with
 209 interrupts disabled.
 210 This means that the clock stops while they are printing.
 211 A machine with many disk or network hardware problems and consequent
 212 messages cannot keep good time by itself.
 213 Each message typically causes
 214 the clock to lose a dozen milliseconds.
 215 A time daemon can correct the result.
 216 .Pp
 217 Messages in the system log about machines that failed to respond
 218 usually indicate machines that crashed or were turned off.
 219 Complaints about machines that failed to respond to initial time
 220 settings are often associated with
 221 .Dq multi-homed
 222 machines that looked for time masters on more than one network and eventually
 223 chose to become a slave on the other network.
 224 .Sh WARNINGS
 225 Temporal chaos will result if two or more time daemons attempt
 226 to adjust the same clock.
 227 If both
 228 .Nm
 229 and another time daemon are run on the same machine,
 230 ensure that the
 231 .Fl F
 232 flag is used, so that
 233 .Nm
 234 never attempts to adjust the local clock.
 235 .Pp
 236 The protocol is based on
 237 .Tn UDP/IP
 238 broadcasts.
 239 All machines within the range of a broadcast that are using the
 240 .Tn TSP
 241 protocol must cooperate.
 242 There cannot be more than a single administrative domain using the
 243 .Fl F
 244 flag among all machines reached by a broadcast packet.
 245 Failure to follow this rule is usually indicated by complaints concerning
 246 .Dq untrusted
 247 machines in the system log.
 248 .Sh FILES
 249 .Bl -tag -width /var/log/timed.masterlog -compact
 250 .It Pa /var/log/timed.log
 251 tracing file for
 252 .Nm
 253 .It Pa /var/log/timed.masterlog
 254 log file for master
 255 .Nm
 256 .El
 257 .Sh SEE ALSO
 258 .Xr date 1 ,
 259 .Xr adjtime 2 ,
 260 .Xr gettimeofday 2 ,
 261 .Xr icmp 4 ,
 262 .Xr networks 5 ,
 263 .Xr ntpd 8 ,
 264 .Xr timedc 8
 265 .Rs
 266 .%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
 267 .%A R. Gusella
 268 .%A S. Zatti
 269 .Re
 270 .Sh HISTORY
 271 The
 272 .Nm
 273 utility appeared in
 274 .Bx 4.3 .