Time Synchronization

We strongly recommend keeping the host clock synchronized with NTP (Network Time Protocol). Koios timestamps every device read, model prediction, event, and historical sample using the host clock, so a well-synchronized clock keeps your trends, model history, and event timelines aligned with reality. Koios runs fine without it, but accurate time makes the data far more trustworthy and easier to compare against other systems.

What Synchronized Time Gives You

Area	Benefit
On-host accuracy	Time-series data is written with correct timestamps, so trends, model history, and event timelines line up with reality.
UI freshness	The UI compares its clock against the server clock. Large drift can trigger a warning on the System Overview page and make "live" values look stale or future-dated.
Cross-system comparison	Comparing Koios timestamps against PLC, SCADA, or third-party historians stays reliable when both sides share accurate time.

Check and Enable It

Ubuntu enables systemd-timesyncd automatically on a clean install. Verify it is running and synchronized:

timedatectl status

The output should show System clock synchronized: yes and NTP service: active. If it isn't, enable it:

sudo timedatectl set-ntp true

Set the timezone too. It does not affect stored timestamps, which are always UTC, but it determines how times read in the host's own logs:

sudo timedatectl set-timezone America/Chicago

Pointing at an Internal Time Server

For air-gapped sites, point the host at your own time server. Use a drop-in file so a system upgrade cannot overwrite it:

sudo mkdir -p /etc/systemd/timesyncd.conf.d
sudo nano /etc/systemd/timesyncd.conf.d/site-ntp.conf

[Time]
NTP=<your time server>
FallbackNTP=

Then restart the service:

sudo systemctl restart systemd-timesyncd

A hostname and an address both work, and an address is the better choice on a segment with no internal name resolution. A second server is optional: add it after the first, separated by a space, and it is tried when the first does not answer.

Leave the fallback empty on an isolated network

FallbackNTP defaults to public internet time servers. On an isolated network those are unreachable, and the service can keep retrying them instead of reporting a clear failure. Setting it empty makes an unreachable internal server fail visibly rather than quietly.

Confirm which server it actually settled on:

timedatectl timesync-status

Virtual Machines

Most hypervisors include a guest integration service that pushes the physical host's clock into the virtual machine. If that host is not itself well synchronized, it will periodically pull the guest clock away from your time server. Because the configuration on the guest still looks correct, the symptom is a clock that drifts for no visible reason.

Pick one source of time and disable the other:

Your own time server is authoritative. The usual choice. Disable the hypervisor's guest time synchronization service for this virtual machine, then configure the guest as described above.
The physical host is authoritative. Leave the integration service enabled and make sure the physical host is synchronized. Do not also configure a time server inside the guest.

See Choosing a Host for other guest settings.

Troubleshooting

Check the service log first:

journalctl -eu systemd-timesyncd

Symptom	Cause and fix
`System clock synchronized: no` while the service is active	The server was contacted but its replies were rejected, or it was never reachable. The log lines below identify which.
Repeated timeouts reaching the server	UDP port 123 is blocked between the host and the time server, or the address does not resolve. Try the address directly to separate the two.
Repeated messages about the server's root distance being too large	The time server is reporting a large uncertainty about its own accuracy. See below.
The clock is off by a whole number of hours	This is a timezone setting, not synchronization. NTP corrects fractions of a second, never whole hours. Check the timezone on whichever machine is showing the unexpected time.

Root distance rejections

systemd-timesyncd refuses a time server whose declared uncertainty exceeds five seconds, and logs that it did. There are two causes, and they need opposite responses:

The server is genuinely unsynchronized. It is running but has not locked onto its own upstream source, so it is correctly declining to vouch for its time. No setting on the Koios host fixes this. The time server needs attention.
The server is accurate but reports a conservative uncertainty. Some time server implementations advertise a large margin by default even when their real accuracy is milliseconds. Raise the limit to just above what the server reports:

[Time]
NTP=<your time server>
FallbackNTP=
RootDistanceMaxSec=15

Raise the limit deliberately

Raising RootDistanceMaxSec means accepting time from a source that declines to guarantee better accuracy than that. It is still a large improvement over an unsynchronized host, but if you need timestamps you can defend to the second, the answer is a properly configured time server rather than a higher limit.

What's Next

Installing Docker Engine: install the Docker runtime on the host
System Overview: where clock drift is reported in the UI

Network Configuration Installing Docker Engine