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: src/usr.sbin/timed/timed/timed.8,v 1.7.2.6 2003/03/11 22:31:34 trhodes Exp $
  34 .\" $DragonFly: src/usr.sbin/timed/timed/timed.8,v 1.2 2003/06/17 04:30:03 dillon Exp $
  35 .\"
  36 .Dd June 6, 1993
  37 .Dt TIMED 8
  38 .Os
  39 .Sh NAME
  40 .Nm timed
  41 .Nd time server daemon
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl dtM
  45 .Op Fl i Ar network
  46 .Op Fl n Ar network
  47 .Op Fl F Ar host ...
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility is a time server daemon
  52 which is normally invoked at boot time from the
  53 .Xr rc.network 8
  54 file.
  55 It synchronizes the host's time with the time of other
  56 machines, which are also running
  57 .Nm ,
  58 in a local area network.
  59 These time servers will slow down the clocks of some machines
  60 and speed up the clocks of others to bring them to the average network time.
  61 The average network time is computed from measurements of clock differences
  62 using the
  63 .Tn ICMP
  64 timestamp request message.
  65 .Pp
  66 The following options are available:
  67 .Bl -tag -width indent
  68 .It Fl d
  69 Enable debugging mode;
  70 do not detach from the terminal.
  71 .It Fl i Ar network
  72 Add
  73 .Ar network
  74 to the list of networks to ignore.
  75 All other networks
  76 to which the machine is directly connected
  77 are used by
  78 .Nm .
  79 This option may be specified multiple times
  80 to add more than one network to the list.
  81 .It Fl F Ar host ...
  82 Create a list of trusted hosts.
  83 The
  84 .Nm
  85 utility will only accept trusted hosts as masters.
  86 If it finds an untrusted host claiming to be master,
  87 .Nm
  88 will suppress incoming messages from that host
  89 and call for a new election.
  90 This option implies the
  91 .Fl M
  92 option.
  93 If this option is not specified,
  94 all hosts on the connected networks are treated as trustworthy.
  95 .It Fl M
  96 Allow this host to become a
  97 .Nm
  98 master if necessary.
  99 .It Fl n Ar network
 100 Add
 101 .Ar network
 102 to the list of allowed networks.
 103 All other networks
 104 to which the machine is directly connected
 105 are ignored by
 106 .Nm .
 107 This option may be specified multiple times
 108 to add more than one network to the list.
 109 .It Fl t
 110 Enable tracing of received messages
 111 and log to the file
 112 .It Pa /var/log/timed.log .
 113 Tracing can be turned on or off while
 114 .Nm
 115 is running with the
 116 .Xr timedc 8
 117 utility.
 118 .El
 119 .Pp
 120 The
 121 .Fl n
 122 and
 123 .Fl i
 124 are mutually exclusive
 125 and require as arguments real networks to which
 126 the host is connected
 127 (see
 128 .Xr networks 5 ) .
 129 If neither flag is specified,
 130 .Nm
 131 will listen on all connected networks.
 132 .Pp
 133 A
 134 .Nm
 135 running without the
 136 .Fl M
 137 nor
 138 .Fl F
 139 flags will always remain a slave.
 140 If the
 141 .Fl F
 142 flag is not used,
 143 .Nm
 144 will treat all machines as trustworthy.
 145 .Pp
 146 The
 147 .Nm
 148 utility is based on a master-slave
 149 scheme.
 150 When
 151 .Nm
 152 is started on a machine, it asks the master for the network time
 153 and sets the host's clock to that time.
 154 After that, it accepts synchronization messages periodically sent by
 155 the master and calls
 156 .Xr adjtime 2
 157 to perform the needed corrections on the host's clock.
 158 .Pp
 159 It also communicates with
 160 .Xr date 1
 161 in order to set the date globally,
 162 and with
 163 .Xr timedc 8 ,
 164 a
 165 .Nm
 166 control utility.
 167 If the machine running the master becomes unreachable,
 168 the slaves will elect a new master
 169 from among those slaves
 170 which are running with at least one of the
 171 .Fl M
 172 and
 173 .Fl F
 174 flags.
 175 .Pp
 176 At startup
 177 .Nm
 178 normally checks for a master time server on each network to which
 179 it is connected, except as modified by the
 180 .Fl n
 181 and
 182 .Fl i
 183 options described above.
 184 It will request synchronization service from the first master server
 185 located.
 186 If permitted by the
 187 .Fl M
 188 or
 189 .Fl F
 190 flags, it will provide synchronization service on any attached networks
 191 on which no trusted master server was detected.
 192 Such a server propagates the time computed by the top-level master.
 193 The
 194 .Nm
 195 utility will periodically check for the presence of a master
 196 on those networks for which it is operating as a slave.
 197 If it finds that there are no trusted masters on a network,
 198 it will begin the election process on that network.
 199 .Pp
 200 One way to synchronize a group of machines is to use an
 201 .Tn NTP
 202 daemon to
 203 synchronize the clock of one machine to a distant standard or a radio
 204 receiver and
 205 .Fl F Ar hostname
 206 to tell its timed daemon 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.  Each message typically causes
 213 the clock to lose a dozen milliseconds.  A time daemon can
 214 correct the result.
 215 .Pp
 216 Messages in the system log about machines that failed to respond
 217 usually indicate machines that crashed or were turned off.
 218 Complaints about machines that failed to respond to initial time
 219 settings are often associated with "multi-homed" machines
 220 that looked for time masters on more than one network and eventually
 221 chose to become a slave on the other network.
 222 .Sh WARNINGS
 223 Temporal chaos will result if two or more time daemons attempt
 224 to adjust the same clock.
 225 If both
 226 .Nm
 227 and another time daemon are run on the same machine,
 228 ensure that the
 229 .Fl F
 230 flag is used, so that
 231 .Nm
 232 never attempts to adjust the local clock.
 233 .Pp
 234 The protocol is based on
 235 .Tn UDP/IP
 236 broadcasts.  All machines within
 237 the range of a broadcast that are using the
 238 .Tn TSP
 239 protocol must cooperate.
 240 There cannot be more than a single administrative domain using the
 241 .Fl F
 242 flag among all machines reached by a broadcast packet.
 243 Failure to follow this rule is usually indicated by complaints concerning
 244 "untrusted" machines in the system log.
 245 .Sh FILES
 246 .Bl -tag -width /var/log/timed.masterlog -compact
 247 .It Pa /var/log/timed.log
 248 tracing file for timed
 249 .It Pa /var/log/timed.masterlog
 250 log file for master timed
 251 .El
 252 .Sh SEE ALSO
 253 .Xr date 1 ,
 254 .Xr adjtime 2 ,
 255 .Xr gettimeofday 2 ,
 256 .Xr icmp 4 ,
 257 .Xr networks 5 ,
 258 .Xr timedc 8
 259 .Rs
 260 .%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
 261 .%A R. Gusella
 262 .%A S. Zatti
 263 .Re
 264 .Sh HISTORY
 265 The
 266 .Nm
 267 utility appeared in
 268 .Bx 4.3 .