Serve time with NTP¶
This page shows how a router serves time to the machines on its networks, so that nodes without
internet access, such as those of an air gap, keep their clocks right. A TimeServer document
lets the router's chrony answer NTP from the clients' address ranges. The router itself follows
the time servers of its own TimeSync, as every node does, and passes that time on.
Before you begin¶
You need a router set up as Set up a router describes, and the secrets file. Its
image must accept the kind TimeServer. Router images do unless their modules set the image
option chalkos.router.ntp.enable to
false. An image without the time server refuses the kind: chalkctl validate reports that it
does not accept kind "TimeServer".
The examples configure a LAN router r1 with the addresses 192.0.2.1/24 and
2001:db8:1::1/64 on lan0, whose clients are in 192.0.2.0/24 and 2001:db8:1::/64.
Add a time server¶
A router has one TimeServer at most:
apiVersion: router.chalkos.dev/v1alpha1
kind: TimeServer
metadata: {name: ntp}
spec:
listen: [192.0.2.1, "2001:db8:1::1"]
allow: [192.0.2.0/24, "2001:db8:1::/64"]
chrony answers NTP from the clients of allow and ignores every other client. The firewall
accepts UDP port 123 from allow to the addresses of listen by itself, ahead of the policies
to local, so no FirewallPolicy is needed. A config whose listen and allow share no family
is refused, as the server would answer no one.
listen holds addresses of the router in the default VRF, where chrony runs. chrony binds one
address per family at most, so it listens on every address of the router, and the firewall alone
keeps NTP on the other addresses closed. An address that Network documents give only to the
links of a VRF is refused, as chrony never sees packets of a VRF's links.
The router serves plain NTP without NTS, so its clients name it with nts: false. The time the
router passes on is the time of its own TimeSync's servers. A router that reaches none of them
answers as unsynchronised, at stratum 16, and its clients refuse that time.
chrony answers each client once every two seconds on average, with bursts of up to 16 answers,
such as those of a client that starts with iburst. It drops the requests beyond that, so a
misconfigured client that polls too often gets fewer answers and loads the router less.
Serve the router's clock without a source¶
localStratum lets the router serve its own clock when it follows no time server, as chrony's
local stratum <n> orphan:
chrony switches to its own clock five minutes after it starts without a source, or once the estimated error of the source it followed grows past one second. Its clients then follow the router's clock, however far it drifts from the real time, and a router whose clock was wrong at boot passes the error on. Give a stratum above that of every other server the clients may reach, such as 10, so they prefer any server that has a real source.
After a boot or a restart of chronyd without a reachable source, such as a delivery that changes
the TimeServer, the router answers as unsynchronised for up to those five minutes. Its clients
refuse the answers meanwhile and keep their clocks running from where they stand.
A production air gap needs accurate time for certificates that other systems check, so give it a
reference clock, such as a GPS receiver with its own NTP server, and name that server in the
nodes' TimeSync. localStratum suits a lab, or keeps the nodes' clocks together while the
reference is away.
Point the nodes at the router¶
Each node names the router in its TimeSync, with nts: false:
apiVersion: time.chalkos.dev/v1alpha1
kind: TimeSync
metadata: {name: time}
spec:
servers:
- {host: "2001:db8:1::1", nts: false}
A TimeSync replaces the default servers, so a node with this one follows the router alone.
Deliver and check¶
Validate the files and deliver them:
The delivery opens the port and restarts chronyd, which reads the time server's config when it
starts. The router's clock keeps running through the restart, and chrony takes up its sources again
within seconds. A TimeServer removed closes the port and restarts chronyd without it.
A node that follows the router shows the router's address on the line time: of its status.
In the router test's lab, the node k1 follows r1 at fd00:300::1:
The diagnostic ntp-clients lists the clients the router answered, as chronyc clients prints
them, followed by chrony's counts of the packets it received and dropped, as
chronyc serverstats prints them. r1 of the same lab printed:
Hostname NTP Drop Int IntL Last Cmd Drop Int Last
===============================================================================
fd00:300::31 3 0 1 - 1 0 0 - -
127.0.0.1 0 0 - - - 1 0 - 0
NTP packets received : 3
NTP packets dropped : 0
Command packets received : 16
Command packets dropped : 0
Client log records dropped : 0
NTS-KE connections accepted: 0
NTS-KE connections dropped : 0
Authenticated NTP packets : 0
Interleaved NTP packets : 0
NTP timestamps held : 0
NTP timestamp span : 0
NTP daemon RX timestamps : 0
NTP daemon TX timestamps : 3
NTP kernel RX timestamps : 3
NTP kernel TX timestamps : 0
NTP hardware RX timestamps : 0
NTP hardware TX timestamps : 0
fd00:300::31 is k1, which sent three NTP requests. NTP counts the requests, Drop those
chrony dropped beyond its rate limit, and Last the seconds since the latest. 127.0.0.1 is
chronyc itself, whose commands chrony counts under Cmd. A client that does not appear sent no
request that reached chrony: check its TimeSync, its route to the router, and that allow holds
the address it sends from. A client with drops polls more often than the rate limit allows. The
diagnostic needs a reader client.
Fix a refused delivery¶
The rules check each TimeServer, and the
validator router compares its listen with the
Network and VRF documents. chalkctl validate and chalkctl config apply run both before
chalkctl sends anything:
| Message | Fix |
|---|---|
TimeServer ntp listens on no address of a family its clients' ranges are of, so it would answer no one; give listen and allow a family in common |
Add an address of the clients' family to listen, or the clients' range of that family to allow. |
TimeServer/ntp: spec.listen: the address fe80::1 is no unicast address the time server can listen on |
Give a global or unique local address of the router. |
TimeServer/ntp: spec.listen[0]: the address 2001:db8:3::1 of listen belongs to links of Network 40-guest in VRF guest alone, so the time server of VRF default never receives its queries; listen on an address of the VRF's links |
Listen on an address of a link in the default VRF. |
What next¶
- Config kinds describes each field of
TimeServer. - Build an air-gapped cluster gives the nodes their time inside an air gap.
- Networking explains how a node keeps its clock.