Quick start TimeKeeper evaluation

The easiest way to test/evaluate TimeKeeper is to setup one computer as a server and another as a client, even if you have no existing time sources. The remainder of this section assumes you are starting with two Linux machines, on the same network and you have followed the “Installation” section.

Configuration

On the server, use the following timekeeper.conf:

SERVENTP=1
SOURCE0() { PPSDEV=self; }
SERVEPTP0() { PTPSERVERVERSION=2; }
ENABLE_WEB_MANAGEMENT=1
WEB_MANAGEMENT_PORT=8080

This will configure TimeKeeper to use the local system clock as a source and provide that time to clients on the network.

Then, on the client, edit timekeeper.conf:

SOURCE0() { NTPSERVER=IP_address_of_server; }
SOURCE1() { PTPCLIENTVERSION=2; }
ENABLE_WEB_MANAGEMENT=1
WEB_MANAGEMENT_PORT=8080

This will use the server machine as a time source, communicating over the network using NTP as a primary source, with a PTP backup. Both the server and the client will start TimeKeeper’s internal web service, configured here on port 8080.

Next start/restart timekeeper to utilize the new configuration

$ systemctl restart timekeeper

Non systemd-based systems can be started similarly with service timekeeper restart.

Verify it’s working

From the command line you can run tkstatus (tkstatus.bat on Windows) to query the status of TimeKeeper and verify that it is working properly. For untruncated status and additional information, including one-way delay, you can run tkstatus -f (tkstatus.bat -f on Windows).

The web tools will be running on both systems, allowing you to view information about the configuration, timing quality and more with your web browser pointed to each machine on the configured port.

You can also review /var/log/timekeeper_0.data and /var/log/timekeeper_1.data for a log of updates. On Windows, the var\log path is in the same location as the TimeKeeper installation. The first column is the time since midnight 1970 January 1st of each update. The 2nd column is the offset from the remote server in seconds. More detailed information about each column is located in the “File formats” section.

Seeing a correction

In production, no other process should drive the clock other than timekeeper. For demonstration purposes, we will adjust the clock on the client and verify it is corrected by timekeeper. As root, on the client run:

$ /opt/timekeeper/release64/baddate .004

Since our client is tracking the server SOURCE0 and we abruptly changed the clock on the client, we should expect to see an abrupt change in time followed by a smooth slewing of the clock back to a time roughly consistent with the source. To verify this expectation we’ll look at the TimeKeeper web interface under the Timing Quality tab:

Troubleshooting

Firewalls and blocked ports

Make sure that you have NTP (port 123) and PTP messages (ports 319 and 320) allowed through the firewalls on each system.

Licensing limitations

If you’re running an evaluation version of TimeKeeper, it may only operate for a limited number of days or weeks before expiring. It may also limit the number of clients it can serve time to. These are evaluation limitations only