.\" $Id: clockspeed-conf.8,v 1.8 2003/04/15 17:00:58 patrick Exp $
.\"
.Dd May 16, 2001
.Dt CLOCKSPEED-CONF 8
.Os
.
.
.Sh NAME
.Nm clockspeed-conf
.Nd configure supervise scripts to run clockspeed client
.
.
.Sh SYNOPSIS
.Nm
.Ar acct
.Ar logacct
.Ar DIR
.Ar protocol
.Ar timeserver-ip
.
.
.Sh DESCRIPTION
.Nm
installs supervise skeletons in order to
run a clockspeed client under djb daemontools supervise control.
.Pp
It makes two supervise skeletons, one for
clockspeed (DIR-speed) and the other for clockadjust (DIR-adjust).
The former runs
clockspeed to keep your clock running evenly, the latter queries a
time-keeping server in certain intervals.  It does not symlink the
resulting service directories into svscans central directory (often
called /service/). You can inspect and change the new services before
doing so manually.
.
.Pp
Options:
.
.Bl -tag -width indent
.
.It Ar acct
Account to run clockadjust -
.Nm
installs the DIR-adjust/run script to drop root
privileges and setuid
.Ar acct .
Suggested username is 'clockspeed'.
.
.It Ar logacct
Account to run multilog -
.Nm
installs the DIR-adjust/log/run script to drop root
privileges and setuid
.Ar acct .
Suggested username is 'log'.
.
.It Ar DIR
Basedir to install supervise skeleton -
.Nm
installs the run and log scripts into DIR-adjust
and DIR-speed. Suggested DIR is /var/service/clockspeed.
The resulting trees must be symlinked to the
/service directory as expected by svscan.
.
.It Ar protocol
Time network protocol to be used for synchronizing -
allowed values are 'tai' or 'ntp'.
.
.It Ar timeserver-ip
IP address of a suitable timeserver. See
http://www.eecis.udel.edu/~mills/ntp/clock2a.html
for public ntp timeservers.
Note that most administrators appreciate a short notice
via email when you are using their server for
synchronizing.
.El
.
.
.Sh ENVIRONMENT
.
.Bl -tag -width indent
.
.It Ev CLOCKSPEED_INSTALLATION
The
.Ev CLOCKSPEED_INSTALLATION
environment variable
is a convenience switch to hint the
.Nm
where to look for the clockspeed binaries and
the adjust sockets.
Defaults to 'DJB'. Allowed values are 'DJB', 'FreeBSD_PORT' and 'custom'.
.
. Bl -tag -width "ETCDIR" -compact indent
.It Ev DJB :
clockspeed binary is expected at /usr/local/clockspeed/bin,
adjust and atto are expected at /usr/local/clockspeed/etc
.
.It Ev FreeBSD_PORT :
clockspeed binary is expected at /usr/local/bin,
adjust and atto are expected at /usr/local/etc/clockspeed/
.
.It Ev custom :
ETCDIR and BINDIR must be set to point to
path of clockspeed binary and path of adjust respectively.
Typically adjust is found in conf-home/etc. See the clockspeed
source for details.
.El
.
.It Ev ETCDIR
Required if 
.Ev CLOCKSPEED_INSTALLATION
is set to 'custom'.
.
.It Ev ADJUSTFILE
Full qualified path to adjust pipe generated by clockspeed. Usually conf-home/adjust. Only required if adjust is not in 
.Ev ETCDIR.
.
.It Ev ATTOFILE
Full qualified path to atto file generated by clockspeed. Usually conf-home/etc/atto. Only required if atto is not in 
.Ev ETCDIR.
.
.It Ev BINDIR
Required if
.Ev CLOCKSPEED_INSTALLATION
is set to 'custom'.
.
.It Ev ADJUST_LOGDIR
defaults to 'main'. clockspeed-adjust will log its output to
DIR/clockspeed-adjust/log/ADJUST_LOGDIR/current.
.
.It Ev VA
if defined,
.Ev ADJUST_LOGDIR
will default to 'clockspeed-adjust' instead of 'main'
.El
.
.
.Sh EXAMPLES
.Pp
The following examples are shown as given to the shell:
.Pp
Configure clockspeed run for djb a standard installation. It expects a
timeserver at ip 10.20.30.40 running taiclockd for synchronisation.
clockspeed binary is expected in /usr/local/clockspeed/bin/, clockspeed
adjust socket is expected in /usr/local/clockspeed/etc/ .
.Bd -literal
.Dl clockspeed-conf clockspeed log /var/service/clockspeed tai 10.20.30.40
.Ed
.
.Pp
Configure clockspeed run for FreeBSD ports installation from /usr/ports/sysutils/clockspeed.
The timeserver to synchronize to is expected to be an ntp/xntp server at 10.10.10.123.
Logging of the adjust service is done to /var/service/clockspeed-adjust/log/clockspeed-adjust/current.
.
.Pp
.Dl env CLOCKSPEED_INSTALLATION="FreeBSD_PORT" VA=yes clockspeed-conf clockspeed log /var/service/clockspeed ntp 10.10.10.123
(in one line)
.
.
.Sh SEE ALSO
.Xr clockspeed 1
.Xr taiclockd 1
.Xr taiclockd-conf 8
.Xr supervise 8
.Xr hier 1
.
http://cr.yp.to/
http://foo42.de/devel/sysutils/clockspeed-conf/
.
.
.Sh NOTES
On FreeBSD systems don't forget to read /usr/local/share/doc/clockspeed/INSTALL-FreeBSD
for leapsecond support.
Short summary:
.
.Dl cd /usr/src/share/zoneinfo
.Dl make -DLEAPSECONDS clean all install ; make clean
.
.Pp
Inspect DIR-adjust/env. There you can reconfigure global settings.
Especially SERVER_IP may be tuned if you opt for another timeserver
after a while. The env/*
settings will not be overwritten on future calls of
.Nm
.
.Pp
.
Inspect DIR-adjust/run,
DIR-adjust/log/run and DIR-speed/run if they are
appropriate for your setup. You may change them and finally you MUST
symlink them into the service directory for activation. The typical
commands to run are 
.Dl ln -s DIR-speed /service/
.Dl ln -s DIR-adjust /service/
.
.
.Sh STANDARDS
.Nm
indirectly violates POSIX
by using leapseconds-aware software.
.
.
.Sh HISTORY
.Nm
appeared initially 2003 on FreeBSD.
.
.
.Sh BUGS
Please report any bugs in
.Nm
to the author.
.
.
.Sh AUTHOR
.Nm
was conceived and written by
.An Patrick Atamaniuk Aq atamaniuk at frobs.net
with contributions by
.An Clemens Fischer
and
.An Karsten Rohrbach.
.