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