Skip to content

fix: keep VM clocks on the Mac's time after sleep - #26

Merged
tieuanhquoc merged 1 commit into
masterfrom
fix/guest-clock-sync
Oct 12, 2026
Merged

tieuanhquoc merged 1 commit into
masterfrom
fix/guest-clock-sync

Conversation

@tieuanhquoc

Copy link
Copy Markdown
Collaborator

What & why

The Docker VM's clock fell behind after the Mac slept — seen 4 days, ~2 days and 11 hours behind — so Postgres now(), logs and signed requests (S3, TLS, JWT) were wrong until DockZ restarted. A VM is frozen while the Mac sleeps (measured: 108 h of wall time, 45.5 h of guest uptime), and nothing in the guest set its clock again: the kernel reads the virtual RTC once at boot, and busybox ntpd shipped but was not enabled.

Two layers:

  • Host push (GuestClockSync + GuestClockSyncScheduler): the Mac's epoch goes over the vsock shell and the guest clock is stepped when more than 2 s off. Runs for the Docker VM and running Alpine machines when the engine comes up, on wake (with retries), on clock and time-zone changes, and every minute. Corrections are written to host.log. Works offline and acts immediately.
  • Guest NTP: new images enable ntpd (provision script and Dockerfile); the sync script enables and starts it on older images.

Also: with the time zone on "follow this Mac", a Mac time-zone change reaches the VM right away instead of at the next restart.

Cloud-image machines (Debian/Ubuntu) have no vsock agent and run their own systemd-timesyncd; they are left alone.

Checklist

  • swift run -c release DockzApp test passes locally (457 checks)
  • No new Swift package dependencies
  • New pure logic has checks in a test-runner-*.swift file
  • User-visible change noted under [Unreleased] in CHANGELOG.md
  • Verified the affected flow in the running app

How I verified it

On a throwaway data folder (-dockz.storageRoot /tmp/dzs), with a disk image built by this branch:

  • New image: ntpd enabled and running, guest clock matches the Mac.
  • Stopped and disabled ntpd (as on an older image), set the guest clock 2 days back: the periodic sync set it right within ~40 s, logged clock: Docker VM was 2 d 0 h behind — set to the Mac's time (periodic check), and re-enabled ntpd.
  • Set the clock 2 days back and paused the DockZ process for 4 minutes (VM kept running): corrected the moment DockZ resumed. In those 4 minutes the ntpd daemon had not corrected it yet. It works (a one-shot ntpd -q stepped a 1 h offset immediately), but its poll interval grows to tens of minutes once settled. So it is a slow backstop for the rare "DockZ hung while the VM runs" case; wake and the 1-minute check are the main path.
  • The shell comparison (offset, absolute value, 2 s tolerance, both directions) is unit-tested by running the real script in /bin/sh with date faked.

Not tested: a real Mac sleep/wake cycle (it can't be triggered from a script); that path is the same sync, triggered by NSWorkspace.didWakeNotification.

🤖 Generated with Claude Code

A VM is frozen while the Mac sleeps and nothing in the guest set its
clock again: the kernel reads the virtual RTC once at boot and ntpd was
not enabled. Clocks were seen hours to days behind (4 d, ~2 d, 11 h),
breaking database now(), logs and signed requests until a restart.

- GuestClockSync: pushes the Mac's epoch over the vsock shell and steps
  the guest clock when it is more than 2 s off; also enables and starts
  busybox ntpd (images built before this pick it up).
- GuestClockSyncScheduler: syncs the Docker VM and running Alpine
  machines when the engine comes up, on wake (with retries), on clock
  and time-zone changes, and every minute; corrections go to host.log.
- "Follow this Mac" time zone now follows a zone change right away.
- New images enable ntpd (provision script and Dockerfile).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown
Contributor

Deploying dockz with  Cloudflare Pages  Cloudflare Pages

Latest commit: 6ef0ce4
Status: ✅  Deploy successful!
Preview URL: https://665c6cb0.dockz.pages.dev
Branch Preview URL: https://fix-guest-clock-sync.dockz.pages.dev

View logs

@tieuanhquoc
tieuanhquoc merged commit d70060e into master Oct 12, 2026
3 checks passed
@tieuanhquoc
tieuanhquoc deleted the fix/guest-clock-sync branch October 12, 2026 05:43
@tieuanhquoc tieuanhquoc mentioned this pull request Oct 12, 2026
1 task done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant