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