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