the djb way


clockctl: an interface to clockspeed

The marking time section described the basic usage of the clockspeed utilities. This section presents a simple wrapper interface for clockspeed called clockctl.

The clockctl script relies on a configuration file named clockspeed.conf installed in /usr/local/etc. We look at this first:

# /usr/local/etc/clockspeed.conf
# configuration support for djb clockspeed (0.62)
# ===
## CLOCKSPEED_HOME=/path/to/clockspeed

## CLOCKSPEED_BIN=/path/to/clockspeed/bin

## CLOCK_TYPE 'ntp' | 'tai'

## CLOCK_IP=""

### that's all, folks!

This configuration file simply defines four variables used by clockctl. The path variables (CLOCKSPEED_HOME and CLOCKSPEED_BIN) allow the clockspeed components to be located without modification to one's $PATH environment. Unless the installation procedure for the clockspeed package has been modified, no change should be required for these variables.

The next two variables describe the master time server this host will be using as a reference.

The CLOCK_TYPE variable describes whether the master time server publishes the NTP protocol or Bernstein's TAICLOCK protocol. The time servers described at:

are all NTP time servers, and CLOCK_TYPE should be set to "ntp".

If syncing to a server running taiclockd as described in the section serving time, CLOCK_TYPE should be set to "tai".

The CLOCK_IP variable should be set to the IP address of the master time server this host will be contacting.

Now we can examine the clockctl script:

# /usr/local/bin/clockctl
# interface to djb clockspeed (0.62)
# ===

# read configuration:
if [ -r /usr/local/etc/clockspeed.conf ] ; then
  . /usr/local/etc/clockspeed.conf
  echo "$0: configuration error: unable to read clockspeed.conf"
  exit 1

# clock_pick function:
  case ${CLOCK_TYPE} in
      ${CLOCKSPEED_BIN}/sntpclock "${CLOCK_IP}"
      ${CLOCKSPEED_BIN}/taiclock "${CLOCK_IP}"
      echo "$0: configuration error: CLOCK_TYPE not recognized"
      exit 1;

# process command:
case $1 in
    echo "Viewing current attoseconds in hardware tick:"
    ${CLOCKSPEED_BIN}/clockview < ${CLOCKSPEED_HOME}/etc/atto
    echo "Obtaining new calibration mark from master server at ${CLOCK_IP}:"
    clock_pick | tee ${CLOCKSPEED_HOME}/adjust | ${CLOCKSPEED_BIN}/clockview
    echo "Setting system clock with master server at ${CLOCK_IP}:"
    clock_pick | ${CLOCKSPEED_BIN}/clockadd && \
    clock_pick | ${CLOCKSPEED_BIN}/clockview
    echo "Checking system clock against master server at ${CLOCK_IP} (clockview):"
    clock_pick | ${CLOCKSPEED_BIN}/clockview
    cat <<END_HELP
clockspeed control:
  atto -- inspect current "attoseconds"
  mark -- obtain new calibration mark for clockspeed
  sync -- set the system clock with master time server
  view -- check system clock against master time server
  help -- this screen

    echo "Usage: $0 [ a|atto | m|mark | s|sync | v|view | h|help ]"
    exit 1

exit 0
### that's all, folks!

Copy this file to /usr/local/bin/clockctl and chmod 755.

The script first reads in the clockspeed.conf file we defined above.

The script then defines a function called clock_pick(). This function runs either sntpclock or taiclock, depending on the definition of the CLOCK_TYPE variable.

Finally, the main script branches according the argument on the command line. The help section describes usage of the script.

For example, to set the system clock with the master time server:

# clockctl sync

To take a new timing mark for a running clockspeed process:

# clockctl mark

Note: this script will be required by the clockspeed service daemons described in a later section.

Copyright © 2002, 2003, Wayne Marshall.
All rights reserved.

Last edit 2003.12.31, wcm.