- Shell 100%
| .gitignore | ||
| kairos.conf.example | ||
| kairos.sh | ||
| kairos.sh.sig | ||
| LICENSE | ||
| README.md | ||
| The-Problem.md | ||
Kairos
Version 1.0.0
Kairos is the god of opportune or critical moments.
Network time hardening for Asuswrt-Merlin. Kairos makes the router's clock trustworthy from the first seconds of boot. It runs chrony with NTS-authenticated servers, and can make every device on the LAN use that time and the router's resolver.
Why time matters
It isn't about precision. Being a few seconds off hurts nobody. It's about whether the time can be faked. Your devices use the clock for security decisions:
- Website certificates: is it expired, or not valid yet?
- Two-factor codes: the 6-digit codes only work if the clock is right.
- DNSSEC, software updates and VPN logins all check the time.
- Logs and schedules: parental controls, firewall rules and "what happened when" all assume the clock is true.
Normal NTP has no protection at all. The router has no battery-backed clock, so at boot it believes the first answer it gets, and anyone who can get a packet to it first can tell it any time they like. Set the clock back and expired or revoked certificates look valid again. Set it forward and secure sites, DNSSEC and two-factor codes start failing.
What Kairos changes
- At boot the clock is set within seconds from Cloudflare's anycast addresses, then verified and kept by NTS as soon as the USB drive is up.
- From then on the router takes its time from NTS servers only. NTS is signed time, so a forged answer is rejected.
- Every device on your LAN, including cheap IoT gear that never checks anything, takes its time from the router instead of from random servers on the internet.
- You can see which devices have bad clocks or ignore the router.
Most people will never notice an attack on their time: such attacks are rare today. Think of it as a seatbelt: low cost, nothing installed on your devices, and it closes a gap almost every home network leaves open. It is also the foundation for Astraea (certificate checking), which only works when the time can be trusted.
What leaves the router: Kairos itself talks only to its NTS servers, Cloudflare's anycast time addresses at boot, and Codeberg for its own updates. Nothing about your network or your devices is sent anywhere.
Requirements
- Asuswrt-Merlin with a USB drive and Entware (amtm
ep). In router mode Kairos does everything below. On an access point, repeater, media bridge or AiMesh node it keeps that router's own clock synced and leaves interception and monitoring off. - chrony with NTS support (
chrony-nts) and the Entware CA bundle. The installer offers to install both if they are missing. - ntpMerlin is optional. Without it, Kairos runs chronyd itself. If it is installed, the installer asks whether to keep it (for its graphs) or remove it: see ntpMerlin.
Install
From an SSH session on the router:
curl -fsSL https://codeberg.org/Synastry/Kairos/raw/branch/main/kairos.sh -o /jffs/scripts/kairos.sh
curl -fsSL https://codeberg.org/Synastry/Kairos/raw/branch/main/kairos.sh.sig -o /jffs/scripts/kairos.sh.sig
chmod 755 /jffs/scripts/kairos.sh
/jffs/scripts/kairos.sh install
Entware's chrony-nts package can bring its own start script (S06chronyd), which starts a second chronyd with chrony's default config at boot and on package updates. Kairos (and ntpMerlin) run chronyd from S77chronyd, so Kairos turns the other one off, and again after any package update (the 10-minute check). It notes how the script was set before turning it off, and uninstall puts it back that way (scripts turned off by Kairos before 0.9.69 stay off).
The installer first checks kairos.sh against kairos.sh.sig with the release key (installing Entware's openssl-util if the router's OpenSSL is too old) and stops, changing nothing, if the signature is missing or does not match. No hash to compare by hand.
After installing, kairos works as a short command. Run it without arguments for the menu (install, configure, update, uninstall; e exits), or use the commands below.
The installer first offers the recommended settings (listed on screen): press Enter and it installs with them, then shows a summary and changes nothing until you confirm. Answer no to get the questions instead, one at a time, each with the recommended answer marked; type ? at any question for the details. kairos.sh config later asks the same questions with your current settings as defaults ("currently on"/"currently off"). Astraea and Homonoia ask the same way.
| Step | Question | Recommended |
|---|---|---|
| 1 | Use the Kairos chrony.conf? | Yes. Your current file is saved as chrony.conf.pre-kairos. Answer no to keep your own (GPS, custom servers). |
| 2 | Region | Guessed from the router's time zone |
| 3a | Answer every LAN device's time requests here (NTP intercept)? | Yes. Replaces ntpMerlin's own NTP redirect, which Kairos turns off. |
| 3b | Send LAN DNS to this router's resolver too (DNS intercept)? | No. Sends LAN DNS that nothing else handles to the router; existing redirection (DNS Director, YazFi, VPN Director, your own rules) keeps priority. Run kairos audit dns first. |
| 3c | Watch LAN device clocks (monitor)? | Yes. In memory only. |
With the NTP intercept on, the router also accepts UDP 123 (NTP) from every LAN-side interface. Guest networks (Guest Network Pro, YazFi) usually may reach the router only for DNS and DHCP, so without this their clients would get no time. Nothing else is opened, and chrony's allow list still decides who is answered. The installer says so before you confirm.
Whatever the answers, Kairos always:
- runs chronyd IPv4-only (
-4) - syncs the clock by IP at boot, before the USB disk check
- reports DNS resolver state
Reboot once after installing to start the boot pipeline.
Uninstall
kairos.sh uninstall (or z in the menu) removes every trace: hook lines, firewall rules, cron jobs, the web page, /jffs/addons/kairos.d, the kairos command, its nvram flags and the script itself. It restores your previous chrony.conf and firmware NTP servers, and puts back anything it turned off in other add-ons (ntpMerlin's NTP redirect, scMerlin's NTP boot watchdog, DNS Director). With ntpMerlin, it stays on chronyd with USB storage and chrony-nts stays installed. Without ntpMerlin, Kairos stops chronyd and removes its S77chronyd and /opt/share/kairos.d, and the router's own NTP client keeps the clock again. chrony-nts is removed only if Kairos installed it (recorded from 0.9.69 on; older installs keep it). The Entware packages ca-bundle, tcpdump and openssl-util stay installed.
The Kairos chrony.conf
Two global anchors plus three NTS servers for your region, all with iburst nts minpoll 6 maxpoll 8:
| Region | Servers |
|---|---|
| All | time.cloudflare.com, any.time.nl |
| NA, North America | ntp1.glypnod.com, kong.rellim.com, ntp1.wiktel.com |
| SA, South America | brazil.time.system76.com, a.st1.ntp.br, b.st1.ntp.br |
| EU, Europe | ntp1.rdem-systems.com, paris.time.system76.com, nts.netnod.se |
| AP, Asia-Pacific | ntpmon.dcs1.biz, ntp.neu.edu.cn, nts.netnod.se |
Per-network fallback. A server that works for most people can be unreachable from one network. When a regional server has given no reply and no NTS cookies for 6 hours straight, Kairos replaces it with the region's first spare that passes an NTS key exchange from your router, at most once a day, logs it, and shows it in status and on the page. If fewer than 3 sources are usable (chrony then stops steering the clock), it acts after 1 hour instead of 6 and without the daily limit. Swapped-out servers are not used again; kairos.sh region <code> returns to the defaults. The two global anchors are never swapped, and your own chrony.conf is never touched.
Asia-Pacific has few public NTS servers. Its spares are the nearest reliable one across the Pacific, then a second server at the university that runs ntp.neu.edu.cn (for mainland China).
| Region | Spares |
|---|---|
| NA | virginia.time.system76.com, ntp2.glypnod.com |
| SA | c.st1.ntp.br, d.st1.ntp.br |
| EU | ntp.3eck.net, ntp1.dmz.terryburton.co.uk |
| AP | oregon.time.system76.com, ntp1.neu.edu.cn |
The file lives at /opt/share/kairos.d/chrony.conf, or at /opt/share/ntpmerlin.d/chrony.conf when ntpMerlin runs chronyd. Kairos regenerates it, so edits there are overwritten. After an update, the 10-minute check regenerates it once, so a change to a region's servers reaches existing installs (chronyd restarts only if a server changed). To keep your own file, answer n in kairos.sh config. ntpMerlin updates only refresh its chrony.conf.default, never this file.
Your own lines: /jffs/addons/kairos.d/chrony.conf.add
Ordinary chrony lines in this file are merged into the Kairos chrony.conf, so the file stays managed and you never edit the generated one. It lives on JFFS (it survives a USB swap or an ntpMerlin removal), and the 10-minute check applies an edited file by itself.
| Your line | What happens |
|---|---|
server, pool, peer, refclock, allow, deny, hwtimestamp, sourcedir, ... |
added alongside Kairos's own (a server without nts is flagged in status) |
a one-value setting (minsources, makestep, local, maxupdateskew, ...) |
yours wins: it replaces Kairos's line, with a # yours (Kairos default was: ...) line above it |
ntstrustedcerts with a set number of 1 or higher (ntstrustedcerts 1 <file>) |
added: the certificate is trusted only for servers that name that set (certset 1 on their line), such as a LAN server with a self-signed certificate |
bindcmdaddress, cmdport, ntstrustedcerts without a set (or set 0), driftfile, ntsdumpdir |
skipped and logged: Kairos needs them (chronyc access, USB paths); a certificate without a set would be trusted for every NTS server |
GPS mode starts as soon as the file has a refclock line: your clock leads (prefer is added if missing), the two global NTS anchors stay as a cross-check (with GPS they make three sources, so chrony can outvote a GPS that goes wrong), the regional servers drop out, and minsources 1 lets the GPS steer alone when the anchors are unreachable. local stratum 5 stays as the fallback. Any of these can be overridden in the file. For example:
refclock SHM 0 refid GPS poll 0 delay 0.1
makestep 0.1 3
Have your own accurate time server? Serve NTS from it and add it to chrony.conf.add. You keep its precision on the LAN and every answer is still authenticated. With a self-signed certificate (an IP address in its subject alternative name):
server 10.0.0.5 iburst nts certset 1
ntstrustedcerts 1 /jffs/addons/kairos.d/myserver.crt
Kairos's public servers stay as a cross-check, so a fault on your server is outvoted. Leave trust off that line (it would stop the others from outvoting it); prefer is fine.
Custom region
The four regions are presets: Kairos keeps their servers and replaces an unreachable one by itself (the fallback above). You can add your own servers to a preset, but not remove the preset's. For full control, choose Custom (the Region dropdown on the page, kairos.sh region custom, or option 5 in kairos.sh config):
- The two anchors always stay. The preset's regional servers are copied into
chrony.conf.add(marked# Custom: from the preset), so nothing changes until you edit the list; then add or remove any of them, on the page or withkairos.sh server add|del. - There is no automatic fallback in Custom. A server that stops answering stays until you remove it.
- A removal is refused if fewer than 3 servers would remain, chrony's minimum (GPS mode excepted).
- Switching back to a region removes the copied lines and restores the preset with its fallback; servers you added yourself stay.
The presets with their fallback are the recommended choice for nearly everyone.
NTS servers are easiest to add with kairos.sh server add <host> (menu 12): it runs the same test as kairos.sh verify <host> and adds the server only if it passes. A server Kairos already uses is not added twice (thanks to maghuro, whose pull request proposed it). With your own chrony.conf (config answer n), this file is not used. Uninstall removes it with the rest of /jffs/addons/kairos.d.
Commands
kairos.sh install guided install (afterwards "kairos" works as a short command)
kairos.sh config change chrony.conf, region and intercepts
kairos.sh region NA|SA|EU|AP|custom switch region and restart chronyd
kairos.sh verify NTS-KE check per server (TCP 4460, TLS + ntske/1, live chronyd cookies)
kairos.sh verify <host> ... would this NTS server work from here? (key exchange, then time replies)
kairos.sh audit [dns] follow a LAN client's NTP and DNS through every rule (read-only)
kairos.sh sources chrony's sources: state, reach, offset, NTS cookies and replies, health verdict
kairos.sh clients [--names] LAN devices using the router's time
kairos.sh events [--names] recent device clock events, newest first
kairos.sh monitor [start|stop|restart|status]
kairos.sh server list|add X|del X your own NTS servers (added only if they pass the NTS test);
in Custom, every server but the two anchors
kairos.sh exempt list|host X|ntp IP|del X exempt a host, or list a LAN time server (GPS)
kairos.sh dns [on|off|dot on|off|doh on|off] the DNS intercept and blocks (status without arguments)
kairos.sh status time, DNS, chrony, intercepts, covered interfaces, checks
kairos.sh update [check|force] update from the published version (amtm: amtmupdate)
kairos.sh fingerprint the release key this copy trusts (compare with the published one)
kairos.sh update-certs [apply|accept] the root certificates this router trusts: what changed,
install a newer bundle by hand, accept the present ones
kairos.sh uninstall [-y] remove Kairos completely and put back what it changed
Private by default. status, audit, sources, clients and verify hide what could identify you, so their output can be shared as it is: IP addresses (LAN, WAN, IPv6 prefixes, Tailscale), MAC addresses, device names, DNS upstreams with account IDs in their address, the outside servers devices tried, and your region and regional servers. Each is replaced by a stable placeholder (lan-1, router-1, mac-1, regional-server-1, ...), so the output still makes sense. Well-known public resolvers and time services (1.1.1.1, 9.9.9.9, time.cloudflare.com, ...) stay readable. Add --names to see everything.
kairos.sh verify <host> ... tests servers that are not in use: the NTS key exchange, then a temporary chronyd source marked noselect (never used for the clock) to prove that NTS cookies arrive and time replies come back. It takes up to 75 seconds and removes the test sources.
Add -y to install or config to accept every default without prompting.
Interception
The NTP intercept is on by default; the DNS intercept is off by default. When enabled, NTP (and DNS) from every LAN-side interface is redirected to the router. That covers the main LAN, VLANs, Guest Network Pro / SDN bridges and YazFi guest radios. Each client is answered on its own gateway address. On an access point, repeater or media bridge the intercepts cannot run (there is no routing of its own): status and the page say "on (inactive: not in router mode)", and chronyd still keeps the device's own clock.
Never touched:
- the WAN interfaces, loopback, OpenVPN (
tun*), WireGuard (wg*), Tailscale and PPP/6in4 tunnels (one exception, below: NTP from devices connected from away) - anything listed in
EXCLUDE_IFACESorEXCLUDE_HOSTSin/jffs/addons/kairos.d/kairos.conf
Devices connected from away: a phone or laptop that uses this router as its Tailscale exit node (TAILMON, kernel mode: tailscale0), or that is connected to one of the router's own VPN servers (WireGuard wgs*, OpenVPN tun2*), sends its traffic through the router, so its time requests are answered by this router too, NTS clients excepted, as on the LAN. Nothing else on those interfaces is touched, and outbound VPN clients (wgc*, tun1*) are left alone. REMOTE_TIME=0 in kairos.conf turns it off. Userspace-mode Tailscale has no tailscale0 interface, so it cannot be served (audit says so).
Exemptions and LAN time servers
kairos.sh exempt host 48:e1:50:97:51:a3 bypass all interception (IPv4, subnet, IPv6 or MAC)
kairos.sh exempt ntp 10.0.0.5 a LAN time server (GPS, PTP, chrony on a Pi)
kairos.sh exempt del 10.0.0.5
kairos.sh exempt list
A LAN time server (NTP_SERVERS) keeps its own upstream NTP, and devices that ask it directly reach it; only NTP is left alone, so the DNS intercept still applies to it. Give it a DHCP reservation, because it is listed by IPv4 address. MAC addresses are best for EXCLUDE_HOSTS, because they survive DHCP changes. Kairos never exempts anything on its own.
A LAN DNS server (Pi-hole, AdGuard Home, Unbound or anything else on another device) is detected whatever the router runs on :53: from DHCP (every dnsmasq instance, guest networks included), dnsmasq upstreams, the WAN DNS setting, and live connection tracking (the router forwarding DNS to a LAN host, or LAN devices querying one directly). With the DNS intercept on, its own lookups would be redirected to the router, so DNS can loop; status and audit warn and show the command to exempt it.
Where redirected DNS goes can be fixed with DNS_REDIRECT_TO in kairos.conf (for example the address your resolver listens on); otherwise: to the address of the interface the client is on, unless the router's resolver does not listen there (AdGuard Home bind_hosts, Unbound interface:). The maintenance job probes each interface and then sends that network's DNS to the main LAN address instead; status shows dns redirect. If nothing answers for an interface, audit warns.
Any redirect or exemption another rule made first keeps priority: VPN Director, YazFi, port forwards and your own NAT rules. Kairos appends its rules after them. After an update, the 10-minute check rebuilds Kairos's firewall rules once, so new rules take effect without a firewall restart or reboot.
- IPv4 NTP is redirected only, and only packets shaped like NTP requests (version 1-4, client or symmetric mode, a whole 48-byte header): other programs that use UDP port 123 (BitTorrent peers, some games) pass untouched. A firewall without the
u32match redirects all of UDP port 123 as before, and the log says so once. Nothing is rejected, so a host exempted by an earlier rule keeps working. NTP flows that existed before the rules changed are cleared from connection tracking (if aconntracktool is installed), so they take the new path at once. - Devices that use NTS themselves (recent Ubuntu, chrony with
nts) are left alone: their requests are authenticated with keys from their own server, which a redirect would break. When a LAN device opens TCP 4460 (the NTS key exchange) to an internet server, the kernel remembers both the device and that server for 7 days (RAM only), and NTP from a remembered device to a remembered NTS server goes through untouched. Anything else is redirected, so the passthrough cannot be opened to just any address. After a reboot such a device is redirected until its next key exchange, which its NTS client makes by itself within a few polls. These devices show as hardened ("NTS client"). Needs the iptablesrecentmatch; audit says when it is missing. - IPv6 NTP is kept out of LAN time entirely: forwarded IPv6 NTP and IPv6 NTP to the router itself are rejected on LAN-side interfaces (including anything another rule redirects there), so every device uses IPv4 and chronyd. WAN traffic and the router's own NTP are untouched. Phones, Windows and most devices fall back to IPv4 by themselves. Linux machines running chrony with IPv6 enabled do not: their sources stay unreachable. Start chrony IPv4-only (add
-4toDAEMON_OPTSin/etc/default/chrony, then restart it), or point it at the router (server <router LAN IP> iburst) instead of outside pools. - DNS (only with the DNS intercept): direct queries to outside resolvers are rejected. Port 853 (DNS over TLS) is not blocked.
Audit
kairos.sh audit reads the live rule set and, for each covered interface, follows a client's NTP packet through it, following jumps into other add-ons' chains. It checks:
- raw: anything that skips NAT
- nat: anything that takes or exempts NTP before Kairos
- filter INPUT: whether the router accepts the redirected packet. Guest Network Pro networks often accept only DNS and DHCP.
Rules that only match multicast or broadcast destinations are not listed: they never see unicast NTP to the router. It also lists live NTP flows from connection tracking (redirected, passed through, the router's own), and checks the firmware NTP server and ntpMerlin's redirect. The installer runs the same checks and shows any problems in its summary.
DNS audit
kairos.sh audit dns (also part of kairos.sh audit) shows where a LAN device's DNS really goes, and whose rule sends it there. Read-only; nothing is changed. It reports:
- The resolver: who serves :53 and on which addresses; AdGuard Home's upstreams (encrypted or plain), its per-domain upstreams (
[/name/]server, shown separately) and private upstreams; dnsmasq's upstreams; the firmware's DNS-over-TLS. - Per network: DNS (UDP/TCP 53) aimed at an outside server: redirected to the router, sent elsewhere, blocked, or passed to the internet, naming the owner of the deciding rule (Kairos, DNS Director, YazFi, Skynet, Tailscale, VPN Director, your own nat-start or firewall-start rules, or the chain), including the exceptions a block makes ("blocked by YazFi, except to 1.1.1.1"). DNS-over-TLS (853), IPv6 DNS, whether the router answers DNS from that network, networks set to "No Redirection" in DNS Director, and devices DNS Director sends elsewhere by MAC (grouped: "3 devices to 1.1.1.2 instead of your resolver"). Rules that decide for some hosts first are listed.
- Address translation that makes your resolver see the router instead of the device: Tailscale's SNAT (its own chain, or a
-s 100.64.0.0/10MASQUERADE rule), NAT loopback (a DoH/DoT name with a public certificate used from inside). - DNS-over-HTTPS (443): it cannot be told apart from web traffic; the audit reports whether Firefox's DoH canary (
use-application-dns.net) is blocked. - Live DNS flows from connection tracking: to the router, redirected to the router, to a DNS server on your LAN (Pi-hole, Unbound) and that server's own upstream queries, redirected elsewhere by another rule (DNS Director or VPN Director to a LAN server or an outside one, named), passed to outside servers (with the first few client → server pairs), and the router's own.
- VPN Director devices whose traffic goes through a VPN client but whose DNS no VPN rule handles (always the case for WireGuard clients; OpenVPN unless Accept DNS Configuration is Exclusive): their lookups use your resolver over the router's own connection.
- IPv6 DNS follows the same rules as IPv4: a rule limited to an output interface counts only when that interface is the WAN.
Existing DNS setups come first. Kairos never changes another add-on's or the firmware's DNS redirection on its own. DNS Director in "Router" mode does what the Kairos intercept does and is left alone, and so is DNS Director sending DNS to a server on your LAN (a Pi-hole, say): networks it redirects are simply handled by it. If DNS Director sends LAN DNS to an outside server instead (bypassing your resolver), Kairos logs it once and kairos.sh config asks whether to turn it off (default: no). DNSDIRECTOR_GUARD=0 stops even the question.
How the DNS intercept works with DNS Director. With the intercept on, Kairos places one small chain (KAIROS_DNS) directly above DNS Director's rules (or where they would be). Rules the firmware put earlier, such as VPN Director's Exclusive DNS, still come first and win. It decides only four things, in this order:
- Fail-open: if nothing listens on the router's DNS port (the resolver crashed, or is restarting for an update) for two checks in a row (checked every minute, by looking at the listening socket; no query is sent), all DNS redirection and DNS blocks are lifted, so devices with their own DNS server keep working. It is logged, shown in
statusand on the page, and undone by itself when the resolver is back. A network whose resolver was still starting at that moment is checked again every minute, for up to 15 minutes, rather than waiting for the 10-minute check. Devices that use the router as their DNS server need the resolver either way. EXCLUDE_HOSTS: their DNS passes untouched, past DNS Director too. One list.- Devices set to "No filtering" in DNS Director: left alone, as chosen there.
- Networks whose gateway has no resolver (a guest network when AdGuard Home listens only on the main LAN address): sent to an address where it answers (
DNS_REDIRECT_TO, or the main LAN address).
Everything else goes on to DNS Director, then to the Kairos intercept. DNS Director's own rules are never edited.
kairos.sh dns shows these settings and changes them as small commands (on, off, dot on|off, doh on|off), which is how Astraea manages DNS when it is installed (manager astraea): then kairos.sh config shows the DNS intercept as managed by Astraea.
The names the router looks up for Kairos itself (the DNS probe name, update and certificate hosts, and the servers chrony uses) are listed in /tmp/kairos/selfq (RAM, name|type|time, the last two hours), so Astraea and other add-ons can tell the router's own lookups from a device's.
Blocking DNS-over-TLS (DNS_BLOCK_DOT=1 in kairos.conf, off by default): TCP and UDP 853 from covered LAN networks to the internet is rejected, so phones with Private DNS fall back to your resolver ("Automatic"), or fail ("Strict" with a named provider). Only forwarded traffic is matched, so the router's own DoT upstream (WAN > DNS Privacy, stubby) keeps working. EXCLUDE_HOSTS are exempt, and traffic leaving through a VPN client tunnel is not touched. Apply with service restart_firewall.
Blocking DNS-over-HTTPS (DNS_BLOCK_DOH=1 in kairos.conf, off by default): DoH is ordinary HTTPS on port 443, so it cannot be told apart from web traffic and cannot be blocked by port. What can be blocked is the big public resolvers' own addresses: TCP and UDP 443 from covered LAN networks to Cloudflare, Google, Quad9, AdGuard DNS, OpenDNS, NextDNS, Control D and CleanBrowsing (a short list built into Kairos: addresses used only for DNS, so no website is lost; nothing is downloaded). That catches devices and apps with a hard-coded resolver. Names (dns.google, cloudflare-dns.com, ...) are for your resolver's blocklists (HaGeZi's DoH/VPN bypass list, for example), and Firefox's canary is checked by kairos audit. The router's own DoH upstreams are not affected (forwarded traffic only), EXCLUDE_HOSTS are exempt, and VPN client tunnels are not touched. Apply with service restart_firewall.
Who uses encrypted DNS, blocked or not. Whenever Kairos has DNS rules in place (the DNS intercept or either block), every LAN device that uses DoT, or DoH to one of the listed resolvers, is remembered by the kernel (the iptables recent match, RAM only, by address), blocked or not. So you can see who a block would refuse before turning it on, and who it refuses once it is on: kairos dns seen, the encrypted dns line in status, and Astraea's page. The resolver address each attempt went to is remembered the same way, in one more list (kairos_encdst), so Astraea can show which resolver a device tried. Only the first packet of each connection is looked at, so web traffic is not slowed.
Allowing a device anyway: kairos dns allow add <address | subnet | MAC> (and del, list) keeps one device's DoT/DoH working when the blocks are on, for example a phone with a fixed Private DNS provider. It is DNS_BLOCK_ALLOW in kairos.conf; MACs survive DHCP changes. Its plain DNS is still intercepted; EXCLUDE_HOSTS remains the way to leave a device out of everything. With Astraea managing DNS, its page has an Allow / Remove button per device.
DoH to a server that is not on the list (a private one, or malware with its own) cannot be stopped without breaking open TLS, which Kairos does not do. It does not go unseen: a device that uses this router's time but never looks anything up through your resolver is listed as not covered (Astraea).
Phones and Private DNS, with the DoT and DoH blocks on:
- Android, Private DNS "Automatic" (the default): nothing to change. At home it falls back to your resolver; elsewhere it keeps using encrypted DNS when the network offers it.
- Android, a named provider (strict mode): it never falls back, so at home it shows "Private DNS server cannot be accessed". Either switch it to Automatic, or exempt that phone (
kairos exempt host <its MAC>): it keeps its own encrypted DNS everywhere, and at home it is then not covered, by your choice. - iPhone (an encrypted DNS profile or app): most profile generators can exclude Wi-Fi networks. Exclude your home network, and the phone uses encrypted DNS everywhere else and your resolver at home.
- Tailscale (or another VPN home) with your router's resolver as its DNS: the same resolver at home and away, encrypted inside the tunnel.
Other add-ons Kairos adjusts
Kairos turns off scMerlin's NTP boot watchdog (it kills every ntpd process during boot, including the Kairos boot sync) the way scMerlin's own toggle does: its init-start line and its setting flag are removed, so scMerlin's page shows it off too. scMerlin's other options, including its NTP Ready startup check and TailTaintDns, are left alone.
With the NTP intercept on, Kairos turns off ntpMerlin's own NTP redirect (ntpmerlin → 2), and turns it off again if it is re-enabled. ntpMerlin's DHCP option 42 line is kept: it tells clients the router is their time server.
ntpMerlin
If ntpMerlin is installed, the installer asks: "The addon ntpMerlin is optional. You can keep it for the graphs if you'd like. Keep, Remove, or Cancel? [k/r/c]"
- Keep: ntpMerlin runs chronyd and draws its graphs. Kairos switches it to chronyd with USB storage if needed, through ntpMerlin's own settings.
- Remove: ntpMerlin's own uninstall removes it, your chrony.conf (and your saved original) move to
/opt/share/kairos.d, and Kairos runs chronyd with its ownS77chronyd(Entware's service format,-4, config on USB).
A router that installed Kairos before 0.9.34 is asked the same question once, the next time kairos.sh update runs in a terminal (never from amtm or cron; Cancel asks again).
Afterwards Kairos follows what is installed: if you later install ntpMerlin, it runs chronyd from then on; if you uninstall it, Kairos takes over. The 10-minute check and kairos.sh update do this, log it once, and never remove anything on their own.
Boot: one trigger, two parallel threads
wan-event connected ──► bootstrap NTP by IP (Cloudflare anycast) ──► kairos_time=synced
(not in router mode, there is no WAN event: services-start starts the bootstrap)
Thread 1, storage: pre-mount waits for kairos_time ──► amtm disk check ──► USB mount
Thread 2, resolver: dnsmasq on :53 ──► Entware up ──► :53 resolver answers ──► kairos_dns=hot
- Cable modems: the first attempt waits 5 s after the WAN comes up, and retries are 10 s apart for up to 3 minutes, so a burst at link-up cannot trip a CMTS NTP rate limit. Each distinct failure is logged once (UDP 123 in use, no reply, ntpd killed by the firmware, or an unexpected exit), the first one with a WAN check (does the gateway answer, does Cloudflare answer a ping), and the bootstrap ends with a summary: attempts, seconds, and which client won.
- Log timestamps at boot: the router restores the time it saved at shutdown, so until the first sync its clock is behind by about the length of the reboot. Kairos logs how far the sync moved it ("Router clock corrected by +95 s"), so the jump in timestamps is not mistaken for a delay.
- Bootstrap is Cloudflare anycast by IP (162.159.200.1, 162.159.200.123), never a hostname. The firmware's own NTP client is pointed at the same two addresses (your previous servers are saved and restored on uninstall), so whichever ntpd sets the clock first, the source is Cloudflare. Once chronyd is synchronised, Kairos stops the firmware client: chronyd (NTS) alone keeps the clock, and Kairos stops the client again if the firmware restarts it (logged once per boot). The client is
ntpdon older firmware andntpon 388 and later; both are found. - The firmware's NTP client afterwards. The firmware restarts its own NTP client by itself (a WAN event, a time setting, on some routers every day) and Kairos can only stop it once it runs. So while chronyd is synchronised, the router's own plain NTP requests are turned around to its own chronyd: the client is answered with the NTS time the router already has and cannot move the clock. This is two firewall rules in RAM (chains
KAIROS_OUTandKAIROS_POSTin the nat table). Plain and NTS requests are told apart by size, so chronyd's own traffic is untouched. The rules exist only while chronyd is synchronised to a real source it can hear, all its sources are NTS, the firmware's NTP server for the LAN is off and no bootstrap is running. Otherwise they are removed and the client reaches Cloudflare as before. Kairos restarts nothing and changes no setting for this. Any other program on the router that asks plain NTP gets the router's NTS time too.kairos statusshows the state on the lineown NTP. A firewall without the u32 match gets no rules: there Kairos stops the client and watches the clock. - Bootstrap is plain NTP via BusyBox ntpd, by design. With no RTC the router needs some time immediately, and chrony is only available once the USB drive is checked and mounted.
- Thread 1 never touches the USB disk. pre-mount holds the disk check for at most 90 s.
- Thread 2 is resolver-agnostic: dnsmasq, AdGuardHome, Unbound, NextDNS, Pi-hole and others. It declares
hotwhen the resolver on :53 answers after USB is up. - The DNS check behind "DNS resolver: hot" looks up
DNS_PROBE_NAME(defaulttime.cloudflare.com, a name the router needs anyway and no blocklist blocks; installs that still had the old defaultone.one.one.one, which DoH-bypass blocklists block, are switched automatically) at the router's LAN address. With the DNS intercept on it runs every 10 minutes, because the intercept needs a resolver that answers. With it off, it runs only during boot and when you runkairos.sh status, so there are no recurring queries. - Health comes from chronyd itself: "Healthy" means it is synchronised and has updated the clock recently (within 4 update intervals, at least 15 minutes). Every source chronyd has accepted counts as usable, including those on standby (waiting for a new sample, or less accurate than the selected source and so not averaged); the reason is shown next to it.
- Right after chronyd starts its sources have answered once or twice and are not usable yet; chronyd serves its own clock meanwhile. For the first 10 minutes Kairos shows this as "starting", not as a fault. A source that has never replied shows "never".
Hook lines
install adds one line tagged # Kairos to each hook. A file that already has its line is left exactly as it is.
| Hook | Position |
|---|---|
| init-start | first |
| pre-mount, post-mount | first |
| services-stop, unmount | first: stops the monitor (tcpdump runs from USB) so the drive unmounts cleanly |
| wan-event, services-start, firewall-start, nat-start, service-event, service-event-end | appended |
| dnsmasq.postconf, dnsmasq-sdn.postconf | appended: adds DHCP option 42 (see below) |
DHCP option 42
Kairos adds DHCP option 42 to the router's DHCP server, so devices that honour it ask the router for time directly (Linux, many IoT devices). Devices that ignore it (most Windows, Apple and Android) are still caught by the NTP intercept. It is added through the dnsmasq.postconf hook (and dnsmasq-sdn.postconf for guest networks on firmware that runs a separate DHCP server per network), logged once, and left alone if your config already sets it. Turn it off with DHCP_NTP=0 in kairos.conf.
ntp_ready
ntp_ready is the firmware's "clock is synced" flag. ntpMerlin, timeserverd (which starts chronyd) and MerlinAU all wait on it. Kairos sets it:
- as soon as the bootstrap sync has actually set the clock, usually seconds after the WAN comes up
- otherwise, once Entware is mounted, so chronyd can start and correct the clock itself. This is logged as "clock NOT yet verified".
Earlier versions set it at the start of boot in init-start. install removes that line, unless EARLY_NTP_READY=1 is set in kairos.conf.
Kairos state for other add-ons (/tmp/kairos/status)
Kairos publishes its state in RAM, so other add-ons never need nvram to read it. One key=value per line, the whole file replaced every minute and on every change:
time=booting|synced|degraded
dns=booting|dnsmasq|hot|down|failed
dns_owner=the add-on that owns DNS (port 53), or none
boot_failed=0|1
updated=epoch seconds of the last write
version=Kairos version
roots=accepted|changed|unknown (the root watch: the trusted roots match the list you accepted, or not; 0.9.68)
ca_bundle=the root bundle in use (Entware's, or the firmware's on Reaper; 0.9.68)
Read it with plain shell. If updated is more than 3 minutes old, treat the state as unknown: the Kairos tick is not running. If the file is missing, Kairos is older than 0.9.57 (the same values are in nvram as kairos_time, kairos_dns, kairos_dns_owner and kairos_boot_failed). Only read it, never write it.
When the router's nvram hangs
A known firmware bug can leave nvram (and wl) calls hanging forever: the vendor nvram library binds a netlink socket labelled with the caller's process ID, and when a socket some other process inherited still holds that label, the call waits for a reply that never comes. The system log may show _wlcsm_create_nl_socket ... binding netlink socket error.
Kairos is built for it: every nvram call it makes ends after 5 seconds and falls back to the last value it read, writes are kept and replayed once nvram answers, the minute job never runs twice at once (a tick stuck for 5 minutes gets its own stuck calls ended), and the cron job is read straight from the crontab instead of through cru l (which calls nvram). chronyd does not use nvram, so the clock keeps running. Kairos logs the hang once and logs again when nvram answers. It never touches other programs' processes: for their stuck calls, Martinski's CheckStuckProcCmds.sh is the tool; a reboot is the last resort.
Stats and privacy
All statistics are computed in memory. Kairos never writes them to JFFS or USB. A JSON snapshot for the web page is refreshed every minute at /tmp/kairos/state.json. /tmp is RAM, so the snapshot is gone after a reboot.
The web page (Addons > Kairos)
- Graphs of the last 24 hours: clock offset, frequency, stability (RMS offset) and each source's offset, one sample a minute. They live in router memory only (about 0.5 MB at most with the source history) and start over at every reboot; nothing is written to USB or JFFS. For a longer history, ntpMerlin's graphs work alongside Kairos (keep ntpMerlin at install). In "Each source's offset" each source in the legend has a checkbox (with all / none): tick two or three to compare them, and the scale fits the lines shown. The choice is remembered in your browser.
- Source History: a 24-hour strip per NTS source (30 minutes a cell, the worst state seen: healthy solid, degraded striped, unreachable cross-hatched, an empty outline when there is no data, so colour is never the only cue). Hover a cell for the counts, and for a degraded one why: replies rejected, no recent reply, low reach or no NTS cookies. The key is in the section's title bar. RAM only, like the graphs. When chrony switches its source, Recent Events says so.
- Actions: the page is read-only except for Check for update / Install (the same as
kairos.sh update: signature-checked) and your NTS servers (add, tested live first, and remove; the same askairos.sh server add|del) and the Region dropdown (the four presets and Custom; the same askairos.sh region). They go through the firmware's own add-on settings path, and each is logged. Intercept settings stay inkairos.sh config. - Devices table: toggles for names, addresses (IP and MAC), hiding IPv6 rows; a Hardened column ("pending" until a device polls again after chronyd restarts); long health details shortened to "unsteady" (hover for the details); column meanings on hover.
- Sections (Overview, Secure Sources, Source History, Updates & Servers, LAN Clients, Offsets & Stability, Recent Events) each have a collapse toggle at the right of the header; your browser remembers which are collapsed. Actions run in the background: the page does not reload.
- Klock (
KLOCK=1in kairos.conf, off by default): the Quick Internet Setup button at the top of the menu, on every page, shows the router's time and UTC offset and the date, plus "Off by …" when the viewing device's clock is a second or more off; clicking it opens Kairos. Kairos adds one line to the firmware'sstate.jsas served (into another add-on's copy if one serves it, such as scMerlin's, and back within a minute if that copy is rebuilt) that loads its own script; on any firmware where the button is not exactly where expected, or before the router's time is trusted, the button is left alone.KLOCK=0puts it back within a minute. - NTS column: "ok, 8" means the source holds NTS cookies and answered within two polls. "2 cookies, no replies" means it still holds cookies but has stopped answering.
kairos.sh verifytests the NTS key exchange itself. - Anchors: if time.cloudflare.com or any.time.nl never answers, or its NTS key exchange fails, the page,
statusandauditsay so. Both need UDP 123 and TCP 4460 open; never block them (country blocks in a firewall add-on are the usual cause).
The headline is "X of Y devices hardened". Y is every device seen on the covered networks. A device counts as hardened when its latest request was answered by this router, its clock is within 2 s (or it is a privacy client the router answered), and it has no anomaly. 2 s is the most Android itself lets its clock drift before it corrects it. NTS clients that secure their own time count as hardened too. Devices not yet seen asking for time count as not hardened; devices that do not use NTP (see below) are not counted. Exempt devices are counted separately. Devices the router answered in the last day but the monitor has not watched yet (slow pollers after a reboot, such as Windows, which checks about every 9 hours) are shown as pending and left out of both numbers until their next request.
kairos.sh clients and the page (under the LAN Clients table) also show LAN coverage: of the devices on the covered networks (from the router's ARP table) that use NTP, how many are on this router's time. Devices that have not asked are sorted three ways:
- Not seen yet: on the network for less than a day without asking. Counted against coverage.
- Asks rarely: answered by this router before, with no request for over a day. Counted as covered.
- Does not use NTP: on the network for over a day without a single time request. Not counted. See "What Kairos cannot see".
How long each device has been quiet is kept in RAM only, so after a reboot every quiet device is "not seen yet" for a day. clients --names and the page (with Names or Addresses ticked) list the devices in each group.
On a terminal narrower than the table (SSH from a phone) clients prints each device as a short block of two or three lines, and wraps its notes at words; output sent to a file or a pipe is always the table.
kairos.sh clients hides device names, IPs and MACs by default. Devices are numbered (001, 002, ...) by address and shown with the network they are on. --names reveals the details. Names come from the router's custom client names first, then names given in dnsmasq's configuration (dhcp-host, dhcp-hostsfile and small addn-hosts files, which is how YazDHCP names devices, guest networks included), then the name each device reports in its DHCP lease.
Client monitoring
With Entware's tcpdump installed (the installer offers it), Kairos reads every inbound LAN NTP request header. One awk process keeps all state in RAM and refreshes small files in /tmp/kairos every 15 s. Nothing is written to JFFS or USB.
| Signal | Rule | Effect |
|---|---|---|
| Device clock | transmit timestamp (T1) vs router receive time | moving average; target within 2 s (amber above, red above 10 s) |
| Invalid timestamp | one jump to or from more than a day | ignored, not a step |
| Unset clock at boot | first requests far off (1970, firmware date), corrected at first sync | event, no points; 4 times in 24 h: +5 |
| Wrong clock | consistently off by more than a day for over 2 minutes | +1, event |
| Local time | off by an exact number of quarter-hours (e.g. -5 h), within 60 s | shown as "local time", not counted against the 2 s target |
| Silent drift | |offset| > 2 s | counted, no points |
| Step change | > 30 s between two requests | +1, event |
| Linear drift | > 500 ppm (43 s/day) over 10+ min | +1, event |
| Wrong clock | consistent offset > 1 day | event |
| Privacy client | random T1 (huge and jumping) | shown as private, excluded from drift |
| Outside server | request aimed at a server other than the router | with the NTP intercept on it was answered here anyway: shown, one event per device per day, no points. Otherwise +5 once per device and destination per hour |
| Burst sync | a burst after 5+ min of quiet (a device waking up), or at a steady interval (a schedule) | normal, shown green |
| Restart | an irregular burst while the device was actively polling, with no new DHCP request | shown as a restart (unsteady) |
| Reboot | the same burst right after the device asked DHCP again (its lease moved forward) | shown as "reboots" (amber; frequent reboots mean a crash loop, heat or power) |
| Gap | silence far longer than the device's own usual sleep (or interval), while it kept its DHCP lease | shown as a gap (unsteady); the burst after it is not also a restart |
| Away | the same silence, but the device asked DHCP again when it came back (a phone leaving the house) | normal, counted as steady (hover shows how often) |
| Control query | NTP mode 6/7 | +5, event |
| Old protocol | NTP v1/v2 (once per device per day), unexpected mode | +1, event |
| Leaky bucket | -2 points every 5 min; flagged at 20, cleared below 10 | ! in clients |
| Exempt hosts | listed in EXCLUDE_HOSTS |
observed but never scored (exmt) |
If the router's own clock is stepped (bootstrap or chrony), every device would seem to jump at once. Kairos detects that as a router step and resets device baselines instead of flagging devices. A step counts only when it persists (3 packets over 10 seconds): a busy router delivering packets late in a burst is not a step. When a date with sub-second output is available (Entware's coreutils-date), the step is also confirmed against the clocks themselves (wall clock against uptime, read every 5 minutes and when a step is suspected), so packet timing alone never reports one.
The monitor starts after Entware mounts and is restarted by the 10-minute maintenance job if it stops. kairos.sh clients and the JSON snapshot gain Clock and Score columns while it runs.
What Kairos cannot see
- Devices that do not use NTP. Many smart-home devices (plugs, bulbs, cameras, speakers, some TVs) never ask for time. They take it from their maker's cloud inside the same HTTPS connection they use for everything else, or from their phone app. The router sees no time request, so there is nothing to answer and nothing to measure. Kairos lists such a device as "does not use NTP" once it has been on the network for a day without asking.
- This is not the hole Kairos closes. Kairos exists because plain NTP is not authenticated and anyone on the path can forge it. Time that arrives inside an HTTPS connection is protected by that connection's certificate.
- The router still cannot vouch for that time. It is whatever the maker's cloud says.
- It cannot be redirected. Sending the device somewhere else would break its connection (the certificate would not match), and reading inside it would take TLS interception, which Kairos does not do.
- To check one device, power cycle it. A device that uses NTP asks at boot and shows up within a minute.
- Devices that ask very rarely. A computer that syncs once a week looks the same as a device that never asks, until it asks. Windows:
w32tm /resyncin an admin prompt makes it ask now. - Devices that secure their own time with NTS. Their requests are encrypted to their own server and left alone. They count as hardened when the monitor sees them.
- Devices on networks Kairos does not cover, or reached only through another router.
Checks
kairos.sh status summarizes, and kairos.sh audit details, checks of the environment:
- Upstream NTP: UDP 123 blocked while the NTS key exchange works; NTS key exchange failing; replies lost from most servers (ISP rate limiting, common on cable/DOCSIS); the boot sync failing while chrony works (ISP or modem filtering NTP from source port 123). Each problem is also logged once per boot.
- Missing pieces: Entware, chrony-nts (or ntpMerlin set to chronyd on USB), the CA bundle, tcpdump, and an OpenSSL that can check signed updates.
- chronyd's user: chronyd runs as "nobody", which Entware looks up in
/opt/etc/passwd. Kairos links that to the firmware's list when it does not lead to "nobody" (a file is kept aspasswd.kairos-saved). If chronyd still cannot find the user, install and status name the cause in plain words with a one-line fix: Entware's lookup settings, or its lookup library. - Firmware features: older routers may lack the iptables MAC or conntrack match; Kairos says which feature is missing and what stops working.
- Web UI: all 20 add-on page slots taken, or no add-on support.
- JFFS space: warns below 256 KB free. Settings are written safely: a write that fails on a full JFFS leaves the old file unchanged.
- Router mode: on an access point, repeater, media bridge or AiMesh node Kairos keeps the clock synced and leaves interception and monitoring off.
- Integrity: at boot and after any change, Kairos checks itself against
kairos.sh.sig. Every 10 minutes it warns if ntpMerlin's script changed (shown for a day), if chrony uses a source Kairos did not configure, or if a source is not authenticated with NTS. GPS/PPS reference clocks and time servers on your LAN (private addresses) are shown as such, not flagged: forging them needs access to your network. The page headline warns when the selected source is an internet server without NTS. These are tripwires, not defences: any add-on runs as root and could remove them.
Reaper
Reaper is a hardened fork of Asuswrt-Merlin. Kairos runs on it unchanged and fits in as Reaper's guide asks of add-ons:
- Kairos's firewall chains go right behind Reaper's own front chains (
REAPER_HOOK,REAPER_HOOK_F), so Reaper's layers keep the first word. - The DoT/DoH block is Reaper's own (Bastion > Encrypted DNS): one switch for both, its daily address list, the providers' host names answered NXDOMAIN, and its firewall self-test knows about it.
kairos dns dot on(or Astraea's page) switches it; Kairos rejects nothing itself there. A block that was on before is carried over to Reaper's switch once; if you turn Reaper's block off on its own page afterwards, Kairos leaves it off. To let one device keep its own encrypted DNS, set it to No filtering in DNS Director. - The root certificates come from the firmware's own bundle, not from Entware.
Signed releases
Every release is signed with the Kairos release key (Ed25519). The public key is built into kairos.sh, so kairos update and amtm's amtmupdate download kairos.sh and kairos.sh.sig and refuse anything that is not signed with it, or older than what is installed.
Checking the signature needs OpenSSL 3. Older routers (RT-AC68U and other 386 models) ship OpenSSL 1.1.1, which cannot check this kind of signature, so Kairos installs Entware's openssl-util and uses /opt/bin/openssl. Newer routers use their own OpenSSL.
To check a copy you downloaded yourself:
kairos.sh verifyfile kairos.sh kairos.sh.sig
What the signature covers, and what it does not
- Covered: every update. The copy already on the router checks the new script against the release key it holds, before the new script runs, and refuses an older version.
- A first install checks itself. The installer verifies its own signature with the key inside it, and a swapped script could simply skip that. For a first install, compare the fingerprint (
kairos fingerprint, also at the top of the Kairos page) with the one the author publishes outside the repository, or check the download withverifyfilefrom a copy you already trust. - Not covered: everything else on the router. Add-ons run as root, and switching on custom scripts lets anything in
/jffs/scriptsrun as root. amtm, Entware and the packages Kairos needs from it (chrony-nts, the CA bundle) come through their own installers, outside what this signature can vouch for. Entware fetches packages over plain HTTP unless you change that. Install only what you need. - The root certificates. The CA bundle decides which certificate authorities NTS trusts in the end. Kairos does not upgrade it by itself. It remembers the roots this router trusts and reports every root added or removed later, by name: see
kairos update-certs.
Release public key:
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAnVDrNhELRjzx0WqOEvgPyzBU3SQXQCjYUW0czBEwqlg=
-----END PUBLIC KEY-----
Spare public key, kept offline. A release signed with it is accepted too:
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA21f3dglDRhs4ime0IAIsqHAKL3u/V+4p30epECEZdx0=
-----END PUBLIC KEY-----
Changes
-
1.0.0: Spare release key (kept offline) accepted for updates;
kairos fingerprintshows both. A firewall change that collides with another add-on's is tried again instead of failing: at boot Skynet, Kairos and others write rules at once (reported by Radon_82). 30 s after the firewall starts, Kairos checks its rules are in place and rebuilds them once if not, instead of waiting for the 10-minute check. New companion doc: The Problem. -
0.9.71: Only NTP requests to UDP port 123 are redirected to the router; other programs on that port (BitTorrent, some games) pass untouched, and the client monitor ignores their packets (from maghuro's pull request #14, applied with changes: without the firewall's u32 match the old redirect stays, logged once). The SSH menu opens with one line on the router's time: its source, offset and how many sources are NTS (in place of maghuro's pull request #5). On Reaper the Secure Sources states are coloured again. In Source History, chronyd's first 10 minutes show as "starting" (dashed outline) instead of degraded. Each source's offset line has its own dash pattern, so colour is never the only cue. Not in router mode, or turned off, the client monitor reads "off" instead of "not running". Text from the page that Kairos ignores is trimmed before it is logged. The graph history in router memory is about half the size: each line names its sources by number. No false warning that Chrony's state folders could not be given to its account when chronyd changed a file at that moment.
Older releases
-
0.9.70: New Source History section: a 24-hour strip per NTS source, and Recent Events now shows when chrony switches its source (from maghuro's pull request #13, applied with changes). "NTS Sources" is now "Secure Sources" and "Last 24 Hours" is now "Offsets & Stability"; sources are listed by name everywhere. The graphs follow their section's collapse button; the "Show graphs" box is gone. A source chrony no longer uses (region switch, server removed) leaves the graphs and strips at once. On a busy router, Kairos no longer reports false "router clock corrected by about 0.5 s" pairs. A kairos.sh replaced by hand now restarts the device monitor too. An update copied in while the 10-minute check runs is applied at once, not at the next check. When chrony throws out most replies because this router stamps some of its requests as sent at time zero (seen with chrony 4.4 on kernel 2.6.36), the page and
kairos statussay so, and a source whose replies are rejected reads "replies rejected" instead of "no replies". -
0.9.69: From maghuro's pull requests, applied with changes. Entware's own accounts are kept when Kairos makes sure chronyd's user exists (#6). Chrony setup problems are logged instead of passing silently (#7). A web page action can't be started while another runs, and a reloaded page keeps showing it (#8). Uninstall removes chrony-nts only if Kairos installed it, and puts Entware's chronyd start script back as it was (#10). A source that holds NTS cookies but has stopped answering no longer shows "ok" (#11).
-
0.9.68: Reaper support, following Reaper's guide: firewall chains sit behind Reaper's, the DoT/DoH block is Reaper's own, and root certificates come from the firmware. One DNS outage gives one warning and one recovery, and the page follows within a minute. Web page buttons no longer look stuck when the browser's clock is ahead.
chrony.conf.addtakesntstrustedcertswith a set number, for a LAN server with a self-signed certificate. README: serving NTS from your own time server. -
0.9.67: The root certificate bundle (what NTS and Astraea trust in the end) is no longer upgraded by Kairos every Sunday. It came from Entware, over plain HTTP unless you changed that, on every Kairos router in a time zone in the same minute. Kairos now only looks each week and says once when a newer bundle is offered;
kairos update-certs applyinstalls it by hand and shows which roots it adds or removes. Kairos also remembers the roots this router trusts and warns when one is added or removed by anything (an Entware update, another script), by name, until you accept it withkairos update-certs accept. The list is one small file on JFFS. "Router clock corrected by ... s at boot" now reports what the time sync corrected; it used to include the firmware restoring the time of the last shutdown (years, on some routers). README: what the release signature covers and what it does not. -
0.9.66: The router clock is watched for a step made by another program. The firmware restarts its own NTP client by itself (a WAN event, a time setting, on some routers every day); until Kairos stops it, that client asks plain NTP servers and sets the clock on what they say (seen to do so 5 seconds after starting). Kairos now stops it about a second after it starts (it was 20), and compares the wall clock with the uptime clock, which shows a step at once. On a step it has chronyd measure its NTS sources: more than a second off, the clock is stepped back and a warning is logged with the sizes; a step chronyd agrees with is logged plainly. While a moved clock is unchecked, Kairos does not report time as synced to Astraea and Homonoia. One more hook is used (
service-event-end). While chronyd is synchronised to NTS sources, the router's own plain NTP requests are answered by its own chronyd (two firewall rules in RAM, removed whenever that stops being true), so a restarted client cannot move the clock in the first place. "Firmware NTP client was running again" is logged once per boot instead of hourly. Fixed: chronyd running on its own local clock was counted as synchronised. At a boot where the WAN came up after chronyd, Kairos then called the clock synced while it was still the boot clock, skipped the bootstrap and stopped the firmware's NTP client. The local clock no longer counts, so the bootstrap runs when the WAN connects. On such a boot Kairos also logged "Clock set ... by the firmware NTP client" when nothing had set the clock yet (it trusted a flag it had set itself); it now waits for a real step of the clock or for chronyd on NTS, and says which one set it. chronyd is asked to look up its time servers as soon as the WAN connects (left alone it took over five minutes), and "Entware USB storage lost" is no longer logged while the drive is simply not mounted yet. Also: the fingerprint of the release key this copy trusts is shown at the very top of the page and bykairos fingerprint(SHA-256 of the public key, worked out on the router from the installed script). Compare it with the one published outside the repository. -
0.9.65:
clients --names: Health is now the last column, after IP, MAC and Name, so a long value (such as "burst sync, 2 gaps, away 1x") no longer pushes them out of line and no row is wider than it needs to be. The Int column fits the longest interface name (a device ontailscale0had its whole row shifted). On a terminal too narrow for the table (SSH from a phone), each device is printed as a short block (who, its numbers, its health) and the lines under the table are wrapped at words. Those lines are now three, not twelve: the numbers that are not zero, without the explanations (they are in "Client monitoring" below and on the page). Reported by XIII. The same on every report command:status,audit,sources,verify,events,dnsand the help are wrapped at words for the terminal they are printed on, with what follows hanging under the text it belongs to, andsourcesprints each source as a short block when its table does not fit. The texts ofinstallandconfigwrap the same way (their questions are left as they are). A number is not split from its unit. Output sent to a file or a pipe is unchanged. -
0.9.64: Devices that never ask for time are no longer counted against coverage. A device on the network for a day without a time request is listed as "does not use NTP" (most smart-home devices take their time from their maker's cloud over HTTPS, which the router cannot see), one the router answered before as "asks rarely", and only the rest as "not seen yet". "X of Y devices hardened" leaves out the devices that do not use NTP. The page shows LAN coverage under the LAN Clients table (the README said it did; it did not). New README section: "What Kairos cannot see".
-
0.9.63: Fixed Kairos restarting a healthy chronyd. To see whether chronyd's command socket works, Kairos asks it for its client list, and it took any "501" in the answer for chronyc's error "501 Not authorised". A device that had asked 501 seconds ago, or had made 1501 requests, was enough: "NTS cannot be confirmed" on the page, then a repair and a restart, several times a day on a busy network. Now only chronyc's own error line counts, the question is asked three times before anything is restarted, and the log says what chronyc answered. A reason quoted from chronyd's log carries its date. An update clears the hourly limit on the repair.
-
0.9.62: Time is set sooner after a boot (chronyd is watched every 2 seconds for the first 3 minutes), and "NTP blocked" is not reported while chronyd is still starting. Routers that are not in router mode (access point, repeater, media bridge) get the right wording and start their time from the main router's gateway. When chronyd turns its command socket off, Kairos reads chronyd's own reason and fixes exactly that (the folder's owner or permissions, a stale socket file, two chronyd processes, chronyc and chronyd from different packages). The page shows NTS as unknown, with "NTS cannot be confirmed right now", when the socket is not answering, and no longer as off.
-
0.9.60: A start script that Entware's chrony-nts package brings along (a second chronyd with default settings, which fought the real one) is turned off. The client monitor confirms a step of the router's clock against the clocks themselves, so a burst of late packets is no longer reported as one. The DNS and NTP intercepts read "on, but inactive" on an access point, repeater or media bridge. The page applies settings in the background without reloading, and every section can be collapsed.
-
0.9.59: chronyd running without its command socket (after an Entware update gave its folders back to root) is noticed and repaired, at most once an hour. Firmware calls made by commands are time-limited, so a stuck one cannot hang them.
-
0.9.57: nvram calls are time-limited (see "When the router's nvram hangs"). chronyd's state files are no longer marked executable.
For older releases see the commit history of the repository.
Upgrading from the old inline scripts
Delete the old inline rules from firewall-start and nat-start yourself, then run kairos.sh cleanup-legacy once. It removes only the old scripts' kind of rule from the FORWARD_INTERCEPT / REDIRECT_INTERCEPT chains (a DNS, DoT or NTP reject or redirect aimed at no particular address), lists every rule it keeps, and removes a chain only once it is empty. Kairos never runs it on its own, because those chain names often hold your own rules too.
License
Kairos is released under the MIT License: use, copy, modify and distribute it freely, including in other products, as long as the copyright notice and license are kept. Releases up to 0.9.36 were published under GPL-3.0-or-later.