Clock Service

The ClockService handles the date and time management of the system. If enabled, it tries to update the system date and time using a Network Time Protocol (NTP) server.
NTP can use NTS as authentication mechanism through chrony.

With the default chrony-advanced provider, chrony can also use other time sources. The default configuration has four tiers of time sources, in this order: authenticated NTP (NTS), plain NTP, GPS and cellular network time (NITZ). For details, see Default configuration: NTS with multiple fallbacks.

Service Configuration

To manage the system date and time, select the ClockService option located in the Services area as shown in the screen capture below.

The ClockService provides the following configuration parameters:

enabled - sets whether or not this service is enabled or disabled. (Required field.)
clock.set.hwclock - defines if the hardware clock of the gateway must be synced after the system time is set. If enabled, the service calls the Linux command "hwclock --utc --systohc".
clock.provider - specifies one among Java NTP client (java-ntp), Linux chrony command (chrony-advanced), Linux ntpdate command (ntpd). (Required field.)
If chrony-advanced is used, ESF will not change system and/or hardware clock directly, delegating these operations to chrony.
clock.ntp.host - sets a valid NTP server host address.
clock.ntp.port - sets a valid NTP port number.
clock.ntp.timeout - specifies the NTP timeout in milliseconds.
clock.ntp.max-retry - defines the number of retries when a sync fails (retry at every minute). Subsequently, the next retry occurs on the next refresh interval.
clock.ntp.retry.interval - defines the interval in seconds between each retry when a sync fails. If the clock.ntp.refresh-interval parameter is less than zero, there is no update. If the clock.ntp.refresh-interval parameter is equal to zero, there is only one try at startup. (Required field.)
clock.ntp.refresh-interval - defines the frequency (in seconds) at which the service tries to sync the clock. Note that at the start of ESF, when the ClockService is enabled, it tries to sync the clock every minute until it is successful. After a successful sync, this operation is performed at the frequency defined by this parameter. If the value is less than zero, there is no update. If the value is equal to zero, syncs only once at startup.
chrony.advanced.config - specifies the content of the chrony configuration file. If this field is left blank, the default system configuration will be used. ESF fills this field with the configuration described in Default configuration: NTS with multiple fallbacks. To obtain the hardware clock synchronization the directive rtcsync could be used. The rtcsync directive provides the hardware clock synchronization made by the linux kernel every 11 minutes. For further information: chrony website

The default configuration and some other example configurations are shown below.

Default configuration: NTS with multiple fallbacks

ESF sets chrony.advanced.config to the following configuration by default. It has more than one time source, so the gateway can still set its clock when some sources are not available. For example, this happens when the gateway has no Internet connection, or when the RTC has lost its time because the backup battery is depleted.

# Tiered time sources, in order of preference:
#   1. NTS   (authenticated NTP)  -> "prefer trust"
#   2. NTP   (unauthenticated)    -> normal sources (+ sourcedir)
#   3. GPS   (gpsd, SOCK)         -> refclock with inflated delay
#   4. NITZ  (cellular, SOCK)     -> refclock with larger delay
#
# Requires chrony >= 4.0 (nts, authselectmode, sourcedir, ntsdumpdir).

authselectmode ignore

minsources 1

# Tier 1: NTS
server time.cloudflare.com  iburst nts prefer trust maxpoll 8
server nts.netnod.se        iburst nts prefer trust maxpoll 8
server sth1.nts.netnod.se   iburst nts prefer trust maxpoll 8
server sth2.nts.netnod.se   iburst nts prefer trust maxpoll 8
server ntp1.wiktel.com      iburst nts prefer trust maxpoll 8
server ntp2.wiktel.com      iburst nts prefer trust maxpoll 8

ntsdumpdir /var/lib/chrony

# Tier 2: plain NTP
pool pool.ntp.org iburst maxsources 3 maxpoll 8
sourcedir /etc/chrony/sources.d

# Tier 3: GPS via gpsd
refclock SHM 0 refid GPS poll 4 precision 1e-3 offset 0.128 delay 0.5
# If the receiver has a PPS line wired up, gpsd also fills SHM unit 1:
#refclock SHM 1 refid PPS poll 4 precision 1e-7 delay 0.5

# Tier 4: NITZ
# NITZ bridge daemon provided by Eurotech (requires separate installation)
refclock SOCK /run/chrony.nitz.sock refid NITZ delay 2.0 stratum 4

# Clock handling
makestep 1 -1

driftfile /var/lib/chrony/chrony.drift
dumpdir   /var/lib/chrony

rtcsync

leapsectz right/UTC

cmdport 0

logdir /var/log/chrony

Chrony always uses the most preferred source that is available. The time sources are listed below, from the most preferred to the least preferred:

Tier	Source	chrony directive	Requirements
1	NTS (authenticated NTP)	`server ... nts prefer trust`	Internet connection.
2	Plain NTP	`pool pool.ntp.org`, `sourcedir /etc/chrony/sources.d`	Internet connection.
3	GPS	`refclock SHM 0 refid GPS`	A GPS receiver that `gpsd` manages.
4	NITZ (cellular network time)	`refclock SOCK /run/chrony.nitz.sock refid NITZ`	A cellular modem registered to a network that sends NITZ, and the Eurotech NITZ bridge daemon.

Note: sourcedir /etc/chrony/sources.d adds the NTP servers that are set at runtime, for example from DHCP. These servers are part of tier 2, unless their .sources file gives them the nts prefer trust options.

📘
GPS and NITZ are optional. If a GPS or NITZ source is not available on the gateway, chrony shows it as unreachable and uses the other sources. You do not need to change the configuration.

GPS: the GPS source reads the NMEA time that gpsd writes to shared memory segment 0. If the GPS receiver is a module of the cellular modem, set the modem GPS mode to UNMANAGED, so that gpsd can use the serial port. For more information, see Cellular Configuration and Position Service. The offset 0.128 value is the NMEA latency measured for a specific receiver. Measure it again if you change the receiver, the firmware, the baud rate or the NMEA sentences. If the receiver has a PPS line, you can remove the # from the refclock SHM 1 refid PPS line to use PPS.

NITZ: the NITZ source receives the time from the Eurotech NITZ bridge daemon through the /run/chrony.nitz.sock socket. You must install this daemon separately via package manager [INSTALLATION INSTRUCTIONS WIP]. The modem must be registered to a cellular network, but it does not need a data connection.

If the RTC has lost its time, NTS can fail because chrony cannot check the validity dates of the server certificates. With the default configuration, chrony first sets the clock from a fallback tier (NTP, GPS or NITZ). Then the certificate checks work, and chrony uses NTS again. You do not need the nocerttimecheck directive described below.

To check which source chrony is using, run chronyc sources on the gateway. The line that starts with * shows the selected source.

NTS Secure configuration example

This example uses NTS sources only, with no fallback.

server time.cloudflare.com iburst nts prefer
server nts.netnod.se iburst nts prefer
server sth1.nts.netnod.se iburst nts prefer
server sth2.nts.netnod.se iburst nts prefer
server ntp1.wiktel.com iburst nts prefer
server ntp2.wiktel.com iburst nts prefer

sourcedir /etc/chrony/sources.d

driftfile /var/lib/chrony/chrony.drift

logdir /var/log/chrony

maxupdateskew 100.0

rtcsync

makestep 1 -1

leapsectz right/UTC

🚧
If the system stays disconnected from the network for a long time or if the backup battery is not working properly or is depleted, there is the possibility of a synchronization failure due to the client inability to verify the server certificates.
If this happens and no counter action has been taken in the chrony configuration file, the risk is that the gateway will be unable to synchronise again its date and therefore will not be able to connect to the cloud and/or be fully operational.
A possible way to prevent this issue is to temporary disable the certificate verification using the directive nocerttimecheck. This directory will disable the security checks of the activation and expiration times of certificates for the specified number of clock updates and should be used with caution due to the important security implications.

As reported by the official Chrony documentation, disabling the time checks has important security implications and should be used only as a last resort, preferably with a minimal number of trusted certificates. The default value is 0, which means the time checks are always enabled.

An example of the directive is nocerttimecheck 1
This would disable the time checks until the clock is updated for the first time, assuming the first update corrects the clock and later checks can work with correct time.

Simple configuration example

# Use public NTP servers from the pool.ntp.org project.
pool pool.ntp.org iburst

# Record the rate at which the system clock gains/losses time.
driftfile /var/lib/chrony/drift

# Allow the system clock to be stepped in the first three updates
# if its offset is larger than 1 second.
makestep 1 -1

# Enable kernel synchronization of the real-time clock (RTC).
rtcsync