TimeKeeper web interface

We covered the basic features of the web interface in the “Web management”" section, but here we’ll look at a couple of technical specifics.

The web interface will visualize a number of things for you, including:

• Current status
• Configuration
• Time accuracy, network delay, frequency behavior for sources
• Timing client behavior
• A timing map of your network
• Compliance reports about your clients

and more. It also provides an easy way to collect logs for TimeKeeper support. The web interface is available on TimeKeeper clients, servers, and grandmasters. Depending on the license, more or fewer features may be visible, and on grandmasters where there are more hardware features available, there will be more options for management and control.

On TimeKeeper grandmasters, the web interface is also reachable via HTTPS in addition to HTTP automatically. For TimeKeeper clients and other installations HTTPS is enabled by default, but HTTP is disabled (WEB_MANAGEMENT_PORT=-1). These non grandmaster installations now include a self-signed certificate.

The web interface is controlled with 2 primary options, enabling the option and controlling the port it’s listening on:

ENABLE_WEB_MANAGEMENT=1
WEB_MANAGEMENT_PORT=-1

HTTPS support is enabled by default and will serve the web interface via HTTPS on port 443. By default the WEB_MANAGEMENT_PORT is set to -1 so that HTTP is disabled.

Configuring for HTTPS

HTTPS support is provided out of the box on TimeKeeper Grandmasters and other installations like clients, Compliance installations, servers, boundary clocks, and so on. These installations will use a self-signed certificate which means that browsers may, on initial connection, ask the user to confirm that the certificate is acceptable. This is normal and expected. This warning will only occur when using HTTPS, and with most browsers will only need to be accepted once. You can provide your own certificate and key using the instructions below to avoid these warnings.

Configuration of this key and certificate are up to the user to manage as the particular commands and tools used to create the files may vary depending on the host. These files must be in the management/ directory of the TimeKeeper installation:

• cert.key (key file for the certificate)
• cert.crt (HTTPS certificate file)

As an example, here are some possible commands used to create an HTTPS key and certificate:

# openssl genrsa -out /opt/timekeeper/management/cert.key 2048
# yes '' | /usr/bin/openssl req -new -key /opt/timekeeper/management/cert.key -out /tmp/cert.csr
# openssl x509 -req -sha256 -days 365 -signkey /opt/timekeeper/management/cert.key -in /tmp/cert.csr -out /opt/timekeeper/management/cert.crt
# chmod 600 /opt/timekeeper/management/cert.{crt,key}

A more stringent procedure likely applies in a production environment, this is provided for demonstration purposes only.

It’s important to restrict access to the generated files, whether they’re created directly as above or generated elsewhere and put in place manually. Above on Linux chmod is applicable, on Windows an ACL may be more appropriate, the specifics are up to the user to decide.

If a certificate and key exist when upgrading TimeKeeper, they’ll be retained and reused after the upgrade completes. When building a TimeKeeper RPM, the key and certificate is retained in the timekeeper-config package. See the timekeeper-config.spec file for more details.

To disable HTTPS, remove the certificate and/or the key. Without those files TimeKeeper will not provide HTTPS support, but will still serve HTTP on the configured port.

This table summarizes the configuration options for HTTP and HTTPS:

If the private key in use requires a passphrase, that passphrase must be added (in encrypted form) to the TimeKeeper configuration using the HTTPS_KEY_PASSPHRASE option. To encrypt the password for inclusion use the encodepassphrase tool provided with TimeKeeper. For example:

# /opt/timekeeper/release64/encodepassphrase
Enter passphrase: fsmlabs
Please add: 'QCphe+KSxRK/PgGUOstVzQ==' as the value for the appropriate
configuration option in your timekeeper.conf file.
Restart TimeKeeper to apply the change.

would result in this line being added to timekeeper.conf:

HTTPS_KEY_PASSPHRASE='QCphe+KSxRK/PgGUOstVzQ=='

Note that “fsmlabs” is only used here as an example. You need to provide whatever passphrase you specified when creating the private key.

Restricting web access to a particular IP address

There is also a WEB_MANAGEMENT_IP option that may be specified as follows:

WEB_MANAGEMENT_IP=10.10.10.1

This will configure the web management tools to only listen on a specific IP address on the server. If web tools are enabled but this option is left unspecified, browsers will be able to connect from any interface.