TSCclock Installation Procedure
Table of Contents
Installing the kernel version
The kernel version of the TSCclock package is composed of a kernel patch and a daemon running. The last version of the package can be retrieved here. The archive contains the source code of the daemon as well as supported plateform patches.
Patching the kernel sources - Linux
This patch should apply against 2.6.18 source trees. eg. (replacing [path-to-tsc-package] with the location where you unpacked the distribution archive)
$ cd /usr/src/linux-2.6.18 $ patch -p1 < [path-to-tsc-package]/kernel-patches/TSC-Linux-2.6.18.patch
Then build kernel as per normal. It introduces two new config options, TSC_CLOCK and TSC_GLOBALDATA.
Patching the kernel sources - FreeBSD
Patches for different versions of FreeBSD are provided. Patch the FreeBSD kernel source tree as follows (replacing [path-to-tsc-package] with the location where you unpacked the distribution archive)
$ cd /usr/src $ patch -Np0 < [path-to-tsc-package]/kernel-patches/TSC-FreeBSD-x.y.patch
You can now compile this patched version. The patch provides a set of possible configuration files based on GENERIC configuration and adding the required options to compile the TSCclock patched kernel. As an example:
$ cd /usr/src/sys/i386/conf $ config TSC+PPS $ cd ../compile/TSC+PPS $ make depend $ make $ sudo make install
Then reboot the computer if everything was fine.
Installation
Installing the TSCclock package
Installing from sources
Unzip and untar the archive, configure, make and install, everything should be fine.
$ tar -xzf tscsync-x.y.z.tar.gz $ cd tscsync-x.y.z $ ./configure $ make $ sudo make install
There are many ways (for Linux) to have the TSCclock starts at boot time. Following are examples of scripts provided as guidelines to start the clock at boot time and have an easy control on the daemon.
FreeBSD
Create the /etc/rc.d/tscclock file and give execution permission.
#!/bin/sh
#
# PROVIDE: tscclock
# REQUIRE: DAEMON
# KEYWORD: shutdown
tscclock_enable="YES"
tscclock_flags="-d"
tscclock_pidfile="/var/run/tscclock.pid"
. /etc/rc.subr
name="tscclock"
rcvar=`set_rcvar`
command="/usr/local/bin/tscclock"
extra_commands="reload"
load_rc_config $name
start_cmd="echo \"Starting ${name}.\"; /usr/bin/nice -5 ${command} ${tscclock_flags} ${command_args}"
run_rc_command "$1"
Linux
Create the /etc/init.d/tscclock file and give execution permission.
#!/bin/sh -e
### BEGIN INIT INFO
# Provides: tscclock
# Required-Start: mountvirtfs ifupdown $local_fs
# Default-Start: S
# Default-Stop: 0 6
### END INIT INFO
set -e;
PATH=/bin:/usr/bin:/sbin:/usr/sbin:/usr/local/bin:/usr/local/sbin;
SYNC_TSC=`which tscclock`
FLAGS="-d"
PID_FILE="/var/run/tscclock.pid"
case "$1" in
start)
echo "Starting the TSCclock"
exec /usr/bin/nice -5 ${SYNC_TSC} ${FLAGS}
;;
stop)
echo "Stopping the TSCclock"
kill -15 `cat ${PID_FILE}` 2> /dev/null || echo "TSC clock was not running?"
;;
reload)
echo "TSCclock reloading the configuration file"
kill -1 `cat ${PID_FILE}`
;;
restart)
echo "Stopping the TSC clock"
kill -15 `cat ${PID_FILE}` 2> /dev/null || echo "TSC clock was not running?"
echo "Starting the TSC clock"
/usr/bin/nice -5 ${SYNC_TSC} ${FLAGS}
;;
status)
echo -n "TSC clock "
if [ ! -r "$PID_FILE" ]; then
echo "is not running."
exit 3
fi
if read pid < "$PID_FILE" && ps -p "$pid" > /dev/null 2>&1; then
echo "is running with pid $pid."
exit 0
else
echo "is not running but $PID_FILE exists."
exit 1
fi
;;
*)
echo "Usage: $0 {start|stop|reload|restart|status}" >&2
exit 1
;;
esac
exit 0
Running the TSCclock
The TSCclock is installed in /usr/local directory and can be run as a daemon using the startup scripts given above. It can also be run by any user to replay trace files. In the following, only the daemon mode is detailed.
NTP packets stream
The TSCclock relies on a continuous stream of NTP packets exchanges with a stratum 1 server in order to achive accurate synchronisation. This flow of NTP packets can be generated using the NTP daemon on the host machine or by using the ntpdate tool. The time period between two packets impacts the quality of the TSC clock (more packets improve the quality of the clock but add load to the network and the stratum 1 server.
Using the NTP daemon
The number that specifies polling rate in the configuration file is which power of two that should be used. E.g. 4 equal 24 = 16 sec. The NTP configuration file is typically located in the /etc/ directory and called ntp.conf. Example of ntp.conf file:
driftfile /etc/ntp/drift server stratum1.my_org.net minpoll 4 maxpoll 4 prefer
For additionnal options, please refer to NTP documentation
Using ntpdate
The distribution provides a simple script apps/ntpd_simple.sh that can be used to start a continuous flow of NTP packets using ntpdate. A simple way to invoke the script is:
$ apps/ntpd_simple.sh stratum1.my_org.net 16
ntpd_simple.sh will then send NTP packets to stratum1.my_org.net every 16 seconds.
First run and configuration
Using the startup scripts above start and stop the TSC clock. For example for FreeBSD:
$ /etc/rc.d/tscclock start $ /etc/rc.d/tscclock stop
This first run creates a default configuration file: /etc/tscclock.conf. Edit the configuration file according to your configuration before starting the TSCclock again. Some parameters are particularly important to improve accuracy of the clock.
- poll_period: it is important you indicate the time interval you chose when creating the NTP packet stream to the stratum 1 server.
-
temperature_quality: you can specify 3 values describing your temperature environment.
poor: the room where your server is installed undergo wide temperature changes in a day.
good: the temperature environment is pretty stable.
excellent: the host is installed in a air-conditioned server room. - update_clock: leave this boolean value to 1 to ensures the TSCclock is available to other applications.
- src_host: indicate the name or IP address of the host running the TSCclock.
- ntp_host: indicate the name or IP address of the stratum 1 server.
- verbose_level: increase the verbose level for diagnosis purpose.