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 February 11, 2008
  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 .in +2
  81 .ti -2
  82 -
  83 Create a list of trusted hosts.
  84 .ti -2
  85 -
  86 Can take one or more parameters.
  87 .ti -2
  88 -
  89 .Nm
  90 will only accept trusted hosts as masters.
  91 If it finds an untrusted host claiming to be master,
  92 .Nm
  93 will suppress incoming messages from that host
  94 and call for a new election.
  95 .ti -2
  96 -
  97 Use real host names (resolvable by RDNS) not aliases (eg in
  98 .Xr named 8
  99 parlance: use A names, not C names).
 100 .ti -2
 101 -
 102 Use full names eg time1.domain.com not time1.
 103 .ti -2
 104 -
 105 .Fl F
 106 automatically includes the functionality of
 107 .Fl M
 108 ( so
 109 .Fl M
 110 does not need to asserted).
 111 .ti -2
 112 -
 113 If
 114 .Fl F
 115 is not specified,
 116 all hosts on connected networks are treated as trustworthy.
 117 .in -2
 118 .It Fl M
 119 Allow this host to become a
 120 .Nm
 121 master if necessary.
 122 .It Fl n Ar network
 123 Add
 124 .Ar network
 125 to the list of allowed networks.
 126 All other networks
 127 to which the machine is directly connected
 128 are ignored by
 129 .Nm .
 130 This option may be specified multiple times
 131 to add more than one network to the list.
 132 .It Fl t
 133 Enable tracing of received messages
 134 and log to the file
 135 .Pa /var/log/timed.log .
 136 Tracing can be turned on or off while
 137 .Nm
 138 is running with the
 139 .Xr timedc 8
 140 utility.
 141 .El
 142 .Pp
 143 The
 144 .Fl n
 145 and
 146 .Fl i
 147 flags are mutually exclusive
 148 and require as arguments real networks to which
 149 the host is connected
 150 (see
 151 .Xr networks 5 ) .
 152 If neither flag is specified,
 153 .Nm
 154 will listen on all connected networks.
 155 .Pp
 156 A
 157 .Nm
 158 running without the
 159 .Fl M
 160 nor
 161 .Fl F
 162 flags will always remain a slave.
 163 If the
 164 .Fl F
 165 flag is not used,
 166 .Nm
 167 will treat all machines as trustworthy.
 168 .Pp
 169 The
 170 .Nm
 171 utility is based on a master-slave
 172 scheme.
 173 When
 174 .Nm
 175 is started on a machine, it asks the master for the network time
 176 and sets the host's clock to that time.
 177 After that, it accepts synchronization messages periodically sent by
 178 the master and calls
 179 .Xr adjtime 2
 180 to perform the needed corrections on the host's clock.
 181 .Pp
 182 It also communicates with
 183 .Xr date 1
 184 in order to set the date globally,
 185 and with
 186 .Xr timedc 8 ,
 187 a
 188 .Nm
 189 control utility.
 190 If the machine running the master becomes unreachable,
 191 the slaves will elect a new master
 192 from among those slaves
 193 which are running with at least one of the
 194 .Fl M
 195 and
 196 .Fl F
 197 flags.
 198 .Pp
 199 At startup
 200 .Nm
 201 normally checks for a master time server on each network to which
 202 it is connected, except as modified by the
 203 .Fl n
 204 and
 205 .Fl i
 206 options described above.
 207 It will request synchronization service from the first master server
 208 located.
 209 If permitted by the
 210 .Fl M
 211 or
 212 .Fl F
 213 flags, it will provide synchronization service on any attached networks
 214 on which no trusted master server was detected.
 215 Such a server propagates the time computed by the top-level master.
 216 The
 217 .Nm
 218 utility will periodically check for the presence of a master
 219 on those networks for which it is operating as a slave.
 220 If it finds that there are no trusted masters on a network,
 221 it will begin the election process on that network.
 222 .Pp
 223 One way to synchronize a group of machines is to use
 224 .Xr ntpd 8
 225 to
 226 synchronize the clock of one machine to a distant standard or a radio
 227 receiver and
 228 .Fl F Ar hostname
 229 to tell its
 230 .Nm
 231 to trust only itself.
 232 .Pp
 233 Messages printed by the kernel on the system console occur with
 234 interrupts disabled.
 235 This means that the clock stops while they are printing.
 236 A machine with many disk or network hardware problems and consequent
 237 messages cannot keep good time by itself.
 238 Each message typically causes
 239 the clock to lose a dozen milliseconds.
 240 A time daemon can correct the result.
 241 .Pp
 242 Messages in the system log about machines that failed to respond
 243 usually indicate machines that crashed or were turned off.
 244 Complaints about machines that failed to respond to initial time
 245 settings are often associated with
 246 .Dq multi-homed
 247 machines that looked for time masters on more than one network and eventually
 248 chose to become a slave on the other network.
 249 .Sh WARNINGS
 250 Temporal chaos will result if two or more time daemons attempt
 251 to adjust the same clock.
 252 If both
 253 .Nm
 254 and another time daemon are run on the same machine,
 255 ensure that the
 256 .Fl F
 257 flag is used, so that
 258 .Nm
 259 never attempts to adjust the local clock.
 260 .Pp
 261 The protocol is based on
 262 .Tn UDP/IP
 263 broadcasts.
 264 All machines within the range of a broadcast that are using the
 265 .Tn TSP
 266 protocol must cooperate.
 267 There cannot be more than a single administrative domain using the
 268 .Fl F
 269 flag among all machines reached by a broadcast packet.
 270 Failure to follow this rule is usually indicated by complaints concerning
 271 .Dq untrusted
 272 machines in the system log.
 273 .Sh FILES
 274 .Bl -tag -width /var/log/timed.masterlog -compact
 275 .It Pa /var/log/timed.log
 276 tracing file for
 277 .Nm
 278 .It Pa /var/log/timed.masterlog
 279 log file for master
 280 .Nm
 281 .El
 282 .Sh SEE ALSO
 283 .Xr date 1 ,
 284 .Xr adjtime 2 ,
 285 .Xr gettimeofday 2 ,
 286 .Xr icmp 4 ,
 287 .Xr networks 5 ,
 288 .Xr ntpd 8 ,
 289 .Xr timedc 8
 290 .Rs
 291 .%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
 292 .%A R. Gusella
 293 .%A S. Zatti
 294 .Re
 295 .Sh HISTORY
 296 The
 297 .Nm
 298 utility appeared in
 299 .Bx 4.3 .