The TimeMonitor is configured using the properties file conf/timemonitor.properties and additional runtime properties can optionally be specified in the TimeMonitorManager worker configuration. For a configuration example, see How to Configure TimeMonitor.

Application properties

The following application properties are configured in the properties file conf/timemonitor.properties.

The conf/ folder is included on the classpath when running the application using the wrapper script bin/timemonitor-in-background.sh. If the application is run some other way, edit src/timemonitor.properties or make sure conf/ is included in the classpath.

Configuration property

Description

signserver.managedconfig

When set to "true" the Runtime properties are not allowed in the configuration file but are instead queried from the SignServer TimeMonitorManager. In this mode, the TimeMonitor will start up disabled, meaning that the time server and NTP daemon will not be queried until the TimeMonitor gets an updated configuration from SignServer. In this mode, the TimeMonitor will query SignServer every 15 seconds.
Sample value: "true"
(warning) On the SignServer Hardware Appliance, the TimeMonitor is by default configured with signserver.managedconfig=true and the other application properties below are not relevant in this case.

timemonitor.stateweb.enabled

Set to "true" to enable (or "false" to disable) the state web server (health check), see Logging and Monitoring.
Sample value: "true"

timemonitor.stateweb.bindaddress

IP address the server will bind to. Use "0.0.0.0" to bind to all interfaces and give external access to the server.
Sample value: "127.0.0.1"

timemonitor.stateweb.port

TCP port to offer state information (HTTP) on.
Sample value: "8980"

timemonitor.stateweb.threads

Number of threads in the thread pool handling incoming connections.
Sample value: "5"

timemonitor.stateweb.backlog

Maximum number of queued incoming connections to allow. Incoming queued connections exceeding this limit may be rejected. If 0 is specified a system default value is used. Sample value: "0"

signserver.process.url

URL to the SignServer process that will handle the status update. Sample value: "http://localhost:8080/signserver/process"

signserver.statuspropertiesworker.name

Name of the StatusPropertiesWorker that will handle the status update.

(warning) SignServer will have to be configured with either a StatusPropertiesWorker or a TimeMonitorManager with this name. It needs to use an Authorizer which gives the TimeMonitor access. For instance, AUTHTYPE=NOAUTH can be used but that would also give everybody permission to update the status. Instead, as the TimeMonitor is running on the same host as SignServer, it is recommended to use a RemoteAddressAuthorizer and only allow requests from localhost.
Sample value: "StatusPropertiesWorker"

signserver.statusproperty.name

Name of the status property to update for time synchronization status.
Sample value: "TIMESOURCE0_INSYNC"

signserver.leapstatusproperty.name

Name of the status property to update for leap second
status.
Sample value: "LEAPSECOND"

timeserver.ntpdatecommand

Path to the nptdate command executable.
Sample value: "/usr/sbin/ntpdate"

(warning) Only relevant when using the legacy NTP implementation with local NTP commands (NTP implementation set to local-ntp-commands).  As of SignServer 5.11, TimeMonitor is by default using its built-in SNTP support, see runtime property for NTP implementation ntpimplementation below.

timeserver.ntpqcommand

Path to the ntpq command executable.
Sample value "/usr/bin/ntpq"

(warning) Only relevant when using the legacy NTP implementation with local NTP commands (NTP implementation set to local-ntp-commands).  As of SignServer 5.11, TimeMonitor is by default using its built-in SNTP support, see runtime property for NTP implementation ntpimplementation below.

Runtime properties

The following runtime properties can be specified in one of the following ways:

For a configuration example using the TimeMonitorManager, see How to Configure TimeMonitor.

The following lists available runtime properties.

Configuration property

Description

timeserver.ntpimplementation

Choice of implementation for executing NTP queries. Either "local-ntp-commands" or "builtin-sntp".

Optional. As of SignServer 5.11, TimeMonitor is by default using its built-in SNTP support and the default NTP implementation is "builtin-sntp".
Sample value: "builtin-sntp"

Builtin SNTP (builtin-sntp) 

With this option, the NTP queries will be carried out by the TimeMonitor application using its built-in support for SNTP. No additional software is required to be installed in the system.

Multiple time servers can be used for redundancy. The implementation queries all servers in parallel and chooses the results from the server that is first with answering the configured number of queries with success.

The final values for time offset and delay are the average of the values from the chosen server.

In case no server answered with success for the configured number of queries, if the time limit was up, or if any server responded with a kiss-of-death RATE limiting message, the response is considered a failure.

Local NTP Commands (local-ntp-commands)

This is the legacy option which relies on the local system to have the "ntpdate" and "ntpq" commands installed. See also the Application properties timeserver.ntpdatecommand and timeserver.ntpqcommand.

If multiple time servers are specified the ntpdate command will be responsible for choosing which response to use.

The leap second indicator will be queried using the ntpq command and receive its information from the local NTP daemon. Therefore, the local system must run ntpd (and not another implementation like Chrony).

timeserver.host

Hostname or IP address of the time server that should be queried. Can also be a comma-separated list to use several servers. The list of servers to query will be passed to the NTP implementation (see timeserver.ntpimplementation).

Sample value: "192.168.20.10, 192.168.20.11"

timeserver.sendsamples

Number of samples (NTP packets) to send to the time server.

For the Builtin SNTP implementation, this is the number of queries to send to each server. Currently, a response is required for each sample for that server to be considered successfully queried.

For the Local NTP Commands implementation, this is the "-p" option of ntpdate and can be from 1 to 8 inclusive.

Specifying a larger number of samples can give more accurate estimates but may take a longer time to execute.

Sample value: "2"

timeserver.timeout

Maximum wait time for a response from the time server (in seconds with decimals).

For the Builtin SNTP Commands implementation, this is the timeout for each query so the maximum total query time would be at most roughly this time times the number of samples.

For the Local NTP Commands implementation, this is the "-t" option of ntpdate. The unit is seconds, but fractions rounded to a multiple of 0.2 are supported.

Sample value: "0.2"

timemonitor.maxAcceptedOffset

Maximum difference (in milliseconds) for the local time as compared to the time server for the time status to still be INSYNC.
Sample value: "997"

timemonitor.warnOffset

Difference (in milliseconds) for the local time as compared to the time server when the state changes to SOON_OUT_OF_SYNC.
Sample value: "500"

timemonitor.statusExpireTime

Expire time (in milliseconds) to set when publishing the status to SignServer.

(warning) Make sure the TimeMonitor has enough time to run one round and publish a new value before the expiration otherwise SignServer will not be able to issue time-stamp tokens for a period of time.
Sample value: "900"

timemonitor.leapStatusExpireTime

Expire time (in milliseconds) to set when publishing the leap second status to SignServer.
Sample value: "60000"

timemonitor.minRunTime

Minimum time for one round by the TimeMonitor. If checking the time and publishing the status is performed in a shorter time than this value (in milliseconds), TimeMonitor will sleep for the remaining time.
Sample value: "500"

timemonitor.warnRunTime

If performing one round of checking the time and publishing the status exceeds this (in milliseconds), the report state is changed to REPORTED_BUT_EXPIRE_TIME_SHORT, indicating that the time settings need to be adjusted.
Sample value: "700"

timemonitor.disabled

When set to "true", the TimeMonitor is explicitly set in disabled mode, meaning that the time server and NTP daemon will not be queried until the TimeMonitor gets an updated configuration from SignServer. In this mode, the TimeMonitor will only query SignServer every 15 seconds.

For a configuration example using the TimeMonitorManager, see How to Configure TimeMonitor.