fix(minvmd): sync time for guests on MacOS by twitchyliquid64 · Pull Request #961 · gominimal/minimal

twitchyliquid64 · 2026-07-24T23:46:14Z

KVM has a paravirt clock that keeps everything in check, so no issue on Linux hosts. For MacOS hosts, libkrun has its own solution but the guest side only runs if you use libkrunfw / their init, which we dont.

So we do the same thing: listen on their magic vsock timekeeping port 123 when we are an arch that could be macOS, and update the guest clock when we get a periodic message or the time has drifted due to system power states.

Summary by CodeRabbit

New Features
- Added optional guest time synchronization using host-provided timestamps.
- The guest clock now corrects significant time drift automatically.
- Added architecture-specific configuration to enable time synchronization where supported.
Bug Fixes
- Malformed updates and temporary communication interruptions are handled without stopping synchronization.
- Permission failures when adjusting the clock are logged while allowing future updates to continue.

Note

Sync guest CLOCK_REALTIME from host time updates over vsock in minimald

Adds run_timekeep_listener in guest.rs that opens an AF_VSOCK datagram socket and receives 8-byte little-endian host nanosecond timestamps on the configured port.
Steps the guest CLOCK_REALTIME via clock_settime when drift exceeds 80ms; skips malformed packets and logs a one-time warning if CAP_SYS_TIME is missing.
On aarch64, main.rs automatically spawns this listener on port 123 for init-process builds; other architectures leave it disabled unless --timekeep-listener-port is set.
Risk: clock_settime causes a discrete clock step (not a slew), which may affect time-sensitive applications running in the guest.

^{Macroscope summarized a27200f.}

coderabbitai · 2026-07-24T23:46:31Z

📝 Walkthrough

Walkthrough

Adds guest time synchronization over an AF_VSOCK datagram listener, conditionally starts it from minimald, enables required nix features, and tests timestamp decoding and clock adjustment behavior.

Changes

Guest timekeeping

Layer / File(s)	Summary
Vsock timekeeping listener `Cargo.toml`, `crates/minimald/src/guest.rs`	Enables `nix` socket/time features, receives host nanosecond timestamps over vsock, steps `CLOCK_REALTIME` when drift exceeds the threshold, and tests the synchronization logic.
Listener configuration and startup `crates/minimald/src/main.rs`	Adds a hidden listener-port option, configures port 123 on `aarch64`, and starts the listener as a background task when configured.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant LibkrunTimesyncWorker
  participant MinimaldListener
  participant GuestClock
  LibkrunTimesyncWorker->>MinimaldListener: Send host nanoseconds over vsock
  MinimaldListener->>GuestClock: Read current CLOCK_REALTIME
  MinimaldListener->>GuestClock: Step clock when drift exceeds threshold

Suggested reviewers: norrietaylor

Poem

A rabbit hops where timestamps fly,
Through tiny sockets in the sky.
The guest clock drifts, then finds its beat,
With nanosecond paws so neat.
“Sync!” I cheer, and twitch my ear.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description lacks the required Summary, Testing, and Checklist sections, so it does not match the repository template.	Add the template sections with a concise summary, the tests you ran, and the checklist items for docs and BREAKING CHANGE.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is clear and directly matches the PR's main change: guest time synchronization for macOS-related builds.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

_{Comment @coderabbitai help to get the list of available commands.}

msample

Nice. Where did the 80ms threshold come from?

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/minimald/src/guest.rs`:
- Around line 723-725: Update the ready.try_io receive logic in the guest
time-update path to use recvfrom instead of recv, retaining the peer address
returned by the kernel. Reject datagrams whose reported AF_VSOCK peer CID is not
VMADDR_CID_HOST before decoding the 8-byte payload, and only process
authenticated host packets.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a2652a37-90e9-4447-a1be-cd1f176c0d3a

📥 Commits

Reviewing files that changed from the base of the PR and between a0e1610 and a27200f.

📒 Files selected for processing (3)

Cargo.toml
crates/minimald/src/guest.rs
crates/minimald/src/main.rs

twitchyliquid64 · 2026-07-24T23:51:48Z

Nice. Where did the 80ms threshold come from?

I pulled it out of the aether, basic logic was we needed to make it long enough that the delay is unlikely to be caused by vsock or scheduling latency, and 80ms is a solid 6.5 typical timeslices.

fix(minvmd): sync time for guests on MacOS

a27200f

twitchyliquid64 requested a review from norrietaylor July 24, 2026 23:46

twitchyliquid64 enabled auto-merge (squash) July 24, 2026 23:48

msample approved these changes Jul 24, 2026

View reviewed changes

coderabbitai Bot reviewed Jul 24, 2026

View reviewed changes

Comment thread crates/minimald/src/guest.rs

jtnkminimal approved these changes Jul 24, 2026

View reviewed changes

twitchyliquid64 merged commit b0a8579 into main Jul 25, 2026
29 checks passed

twitchyliquid64 deleted the tom/clock branch July 25, 2026 00:02

norrietaylor mentioned this pull request Jul 27, 2026

diag: The guest microVM has no host time synchronization: minimald's timekeep listener cannot bind the libkrun #985

Closed

coderabbitai Bot mentioned this pull request Jul 27, 2026

fix(OSX timekeeping): self-manage timekeeping on OSX #986

Merged

Navigation Menu

Uh oh!

fix(minvmd): sync time for guests on MacOS - #961

fix(minvmd): sync time for guests on MacOS#961
twitchyliquid64 merged 1 commit into
mainfrom
tom/clock

twitchyliquid64 commented Jul 24, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

msample left a comment

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

twitchyliquid64 commented Jul 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

twitchyliquid64 commented Jul 24, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Sync guest CLOCK_REALTIME from host time updates over vsock in minimald

Uh oh!

coderabbitai Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

msample left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

twitchyliquid64 commented Jul 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

twitchyliquid64 commented Jul 24, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading