The first step in using clockspeed is to synchronize your system's clock with a precise time source. A precise time source is one that is synchronized to an atomic clock, measuring the decay of cesium atoms. A number of publicly accessible NTP timeservers are available for this purpose, such as those listed at:

View this page in a browser and select a nearby server offering an open access policy (where nearby is relative to your own Internet connection.) Make a note of the IP address of the server you select. We will illustrate the examples here with the fictitious ntp.example.edu at IP address 1.2.3.4; you will need the IP address of a real timeserver for the examples to actually work.

As super-user add /usr/local/clockspeed/bin to your $PATH environment, eg:

# export PATH=/usr/local/clockspeed/bin:$PATH

For csh or tcsh shells, use:

# set path = ($PATH /usr/local/clockspeed/bin)

Then run the following command:

# sntpclock 1.2.3.4 | clockview
before: 2003-01-02 13:40:52.563877000000000000
after:  2003-01-02 13.40:52.564561499836392700

The sntpclock command will contact the NTP server at IP address 1.2.3.4, determining the adjustment required to synchronize with the NTP server. This output is piped into the clockview command, returning two lines of output as shown above.

The before line shows what your system clock reported, and the after line shows what your system clock would be if it were synchronized with the NTP server. The difference is how far your system is out of whack. If, like me, you set your system time with the date command while eye-balling your wristwatch, the difference will be as much as several minutes.

To bring your system into alignment with the NTP server, now run:

# sntpclock 1.2.3.4 | clockadd

As before, the sntpclock command will contact the NTP server and calculate the adjustment required. This time, though, the output is piped into the clockadd command, actually resetting the system clock by the adjustment amount. Since no output is provided by the clockadd command, check the system again with the clockview command:

# sntpclock 1.2.3.4 | clockview

The difference between the before and after lines should now be negligible.

At this moment, your system clock is pretty well synchronized with the remote time server. But the hardware clock in a typical computer is nowhere near as precise and reliable as the atomic clocks that measure the decay of cesium atoms. Over time, system clocks have a tendency to drift.

To compensate for this drift, clockspeed provides a utility that runs continuously, resetting the system clock every 3 seconds. The clockspeed utility uses 2 sources of information to maintain an accurate system time:

1. a hardware tick counter
2. periodic calibration with an NTP server

In the daemontools chapter, we will configure clockspeed to start automatically with every system boot and run continuously. For now, though, we will demonstrate clockspeed by running it manually.

First, start up clockspeed as a background process:

# clockspeed &

Now, give it an initial real-time calibration mark with an accurate timeserver:

# sntpclock 1.2.3.4 > /usr/local/clockspeed/adjust

Later, after a few hours, give clockspeed another calibration mark:

# sntpclock 1.2.3.4 > /usr/local/clockspeed/adjust

The two calibration marks allow clockspeed to calculate the number of attoseconds (quintillionths, or 10^-18, of a second) in one tick of the hardware tick counter. This value is posted into the file /usr/local/clockspeed/etc/atto, and can be viewed with the command:

# clockview < /usr/local/clockspeed/etc/atto

The precision of the calibration can be improved by repeating the real-time check after a few weeks, and then again after a few months:

# sntpclock 1.2.3.4 > /usr/local/clockspeed/adjust

Now your clock is well and truly set. You will be looking forward to people who ask ``Hey, buddy, you got the time?''

Note: see the clockctl section for a simple interface to the clockspeed functions described above.