OpenBSD-4.6/usr.sbin/timed/timed/timed.8

.\"	$OpenBSD: timed.8,v 1.15 2007/05/31 19:20:30 jmc Exp $
.\"
.\" Copyright (c) 1980, 1991 Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)timed.8	6.7 (Berkeley) 5/11/93
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt TIMED 8
.Os
.Sh NAME
.Nm timed
.Nd time server daemon
.Sh SYNOPSIS
.Nm timed
.Op Fl dMt
.Op Fl F Ar host ...
.Op Fl G Ar netgroup
.Xo
.Oo Fl i Ar network No \&|
.Fl n Ar network Oc
.Xc
.Sh DESCRIPTION
The
.Nm
utility is a time server daemon
which is normally invoked at boot time from the
.Xr rc 8
file.
It synchronizes the host's time with the time of other
machines, which are also running
.Nm timed ,
in a local area network.
These time servers will slow down the clocks of some machines
and speed up the clocks of others to bring them to the average network time.
The average network time is computed from measurements of clock differences
using the
.Tn ICMP
timestamp request message.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl d
Enable debugging mode;
do not detach from the terminal.
.It Fl F Ar host ...
Create a list of trusted hosts.
The
.Nm
utility will only accept trusted hosts as masters.
If it finds an untrusted host claiming to be master,
.Nm
will suppress incoming messages from that host
and call for a new election.
This option implies the
.Fl M
option.
If this option is not specified,
all hosts on the connected networks are treated as trustworthy.
.It Fl G Ar netgroup
Specify a netgroup of trustworthy hosts,
in addition to any masters specified with the
.It Fl i Ar network
Add
.Ar network
to the list of networks to ignore.
All other networks
to which the machine is directly connected
are used by
.Nm timed .
This option may be specified multiple times
to add more than one network to the list.
.Fl M
flag.
This option may only be specified once.
.It Fl M
Allow this host to become a
.Nm
master if necessary.
.It Fl n Ar network
Add
.Ar network
to the list of allowed networks.
All other networks
to which the machine is directly connected
are ignored by
.Nm timed .
This option may be specified multiple times
to add more than one network to the list.
.It Fl t
Enable tracing of received messages
and log to the file
.Pa /var/log/timed.log .
Tracing can be turned on or off while
.Nm
is running with the
.Xr timedc 8
utility.
.El
.Pp
The
.Fl n
and
.Fl i
flags are mutually exclusive
and require as arguments real networks to which
the host is connected
(see
.Xr networks 5 ) .
If neither flag is specified,
.Nm
will listen on all connected networks.
.Pp
A
.Nm
running without the
.Fl M
nor
.Fl F
flags will always remain a slave.
If the
.Fl F
flag is not used,
.Nm
will treat all machines as trustworthy.
.Pp
The
.Nm
utility is based on a master-slave
scheme.
When
.Nm
is started on a machine, it asks the master for the network time
and sets the host's clock to that time.
After that, it accepts synchronization messages periodically sent by
the master and calls
.Xr adjtime 2
to perform the needed corrections on the host's clock.
.Pp
It also communicates with
.Xr date 1
in order to set the date globally,
and with
.Xr timedc 8 ,
a
.Nm
control utility.
If the machine running the master becomes unreachable,
the slaves will elect a new master
from among those slaves
which are running with at least one of the
.Fl M
and
.Fl F
flags.
.Pp
At startup
.Nm
normally checks for a master time server on each network to which
it is connected, except as modified by the
.Fl n
and
.Fl i
options described above.
It will request synchronization service from the first master server
located.
If permitted by the
.Fl M
or
.Fl F
flags, it will provide synchronization service on any attached networks
on which no trusted master server was detected.
Such a server propagates the time computed by the top-level master.
The
.Nm
utility will periodically check for the presence of a master
on those networks for which it is operating as a slave.
If it finds that there are no trusted masters on a network,
it will begin the election process on that network.
.Pp
One way to synchronize a group of machines is to use an
.Tn NTP
daemon to
synchronize the clock of one machine to a distant standard or a radio
receiver and
.Fl F Ar hostname
to tell its timed daemon to trust only itself.
.Pp
Messages printed by the kernel on the system console occur with
interrupts disabled.
This means that the clock stops while they are printing.
A machine with many disk or network hardware problems and consequent
messages cannot keep good time by itself.
Each message typically causes
the clock to lose a dozen milliseconds.
A time daemon can correct the result.
.Pp
Messages in the system log about machines that failed to respond
usually indicate machines that crashed or were turned off.
Complaints about machines that failed to respond to initial time
settings are often associated with
.Dq multi-homed
machines that looked for time masters on more than one network and eventually
chose to become a slave on the other network.
.Sh WARNINGS
Temporal chaos will result if two or more time daemons attempt
to adjust the same clock.
If both
.Nm
and another time daemon are run on the same machine,
ensure that the
.Fl F
flag is used, so that
.Nm
never attempts to adjust the local clock.
.Pp
The protocol is based on
.Tn UDP/IP
broadcasts.
All machines within the range of a broadcast that are using the
.Tn TSP
protocol must cooperate.
There cannot be more than a single administrative domain using the
.Fl F
flag among all machines reached by a broadcast packet.
Failure to follow this rule is usually indicated by complaints concerning
.Dq untrusted
machines in the system log.
.Sh FILES
.Bl -tag -width /var/log/timed.masterlog -compact
.It Pa /var/log/timed.log
tracing file for
.Nm
.It Pa /var/log/timed.masterlog
log file for master
.Nm
.El
.Sh SEE ALSO
.Xr date 1 ,
.Xr adjtime 2 ,
.Xr gettimeofday 2 ,
.Xr icmp 4 ,
.Xr netgroup 5 ,
.Xr networks 5 ,
.Xr ntpd 8 ,
.Xr rdate 8 ,
.Xr timedc 8
.Rs
.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
.%A R. Gusella
.%A S. Zatti
.Re
.Sh HISTORY
The
.Nm
utility appeared in
.Bx 4.3 .