Managing the TimeKeeper service

Once installed TimeKeeper can be started during system boot time like any other system service with the ntsysv, update-rc.d, chkconfig, or systemctl commands, or via the TimeKeeper web interface. On Windows it can be managed via the Windows Service manager or with the sc command.

Once installed, TimeKeeper is listed as the service “timekeeper”. By default it is not configured to start on boot and must be manually enabled. When started on Linux, TimeKeeper will stop services that conflict with proper operation, such as ntpd. If ntpd is running when TimeKeeper is started the ntpd service will be shut down. TimeKeeper will not reconfigure the NTP service to not start at system boot.

To start TimeKeeper by hand on sysvinit-based Linux systems:

# bash /etc/init.d/timekeeper start

Similarly, stop, status, or restart can be used in place of start above to stop, get the status of, or restart the TimeKeeper service, respectively.

If your system is based on systemd, you can start/restart/stop TimeKeeper similarly:

# systemctl start timekeeper

With systemd-based distributions, TimeKeeper also depends on network-online.target so that interfaces and routes are up and configured before TimeKeeper starts.

On Windows TimeKeeper can be started from an elevated command window with:

c:\> sc start timekeeper

Substituting stop for start will stop the TimeKeeper service. The service can also be managed with the normal Windows Service Manager (“services.msc”).

Verify TimeKeeper is working

Within a couple of minutes TimeKeeper should be active and running if the time source is configured properly. You can verify this by running the command tkstatus on Linux, tkstatus.bat on Windows. This will report if TimeKeeper is active or not, what the current clock offset is and how old the latest timestamp is along with the same data about all configured sources. Run tkstatus -f on Linux, tkstatus.bat -f on Windows to report the one-way delay in addition to the base information.

If you’ve enabled the web interface, you can login to TimeKeeper via the web (port 8080 by default) (default passwords are in the “Web interface authentication” section). The Status and Timing Quality tabs on the web interface also provide a clear summary of which source is being used, the current accuracy, and also details on the behavior of the various configured time sources over time.

Also, you can refer to the log files directly. /var/log/timekeeper_0.data (again, located under the TimeKeeper installation directory on Windows) is a running list of every update that TimeKeeper receives and how TimeKeeper is adjusting time for source 0. This file contains a line for every update received from the time source. If it is growing then TimeKeeper is receiving time updates.

In the file, column 1 is the absolute UTC timestamp from the time source in seconds since midnight January 1 1970. Column 2 is the estimated local time offset as of that update. The second column gives a good indication as to the quality of the sync that TimeKeeper has, and will converge shortly after TimeKeeper starts.

For more details on the log file contents, refer to the “File formats” section.

If this file is not being updated, it’s likely that firewalls are preventing receipt of network data, or there is some configuration issue reported in /var/log/timekeeper.

Log rotation

TimeKeeper is provided with two default logrotate recipes that rotate all of the relevant TimeKeeper log files. On Linux this gets installed in /etc/logrotate.d/. By default, this will retain 7 days worth of logfiles. If you have specific log storage needs this value can be easily modified directly or, on the TimeKeeper Grandmaster appliance, via the TimeKeeper web interface.

TimeKeeper’s logrotate configuration options were updated as of 7.2.13. When downgrading from a 7.2.13 or later release to a pre-7.2.13 release, be sure to check logrotate settings because this can result in unexpected values.