From 847df1beb482db677b332a8707d5d19b5a36cbef Mon Sep 17 00:00:00 2001 From: Huy Pham Date: Wed, 16 Sep 2026 13:18:08 -0700 Subject: [PATCH] docs: fix the microVM guide's Lima build-dep list Following docs/dev/microvm-local.md to run hack/microvm-assets/assemble.sh in the Lima guest fails twice over. The git bundled with the guest image does not understand the refstorage repository extension, so cloning virtiofsd aborts with "unknown repository extension found: refstorage". Install a newer git from ppa:git-core/ppa. The list also omits a C compiler, so the arm64 virtiofsd build stops at "error: linker cc not found". Add build-essential. Also record the path-MTU black hole that stalls cargo at zero bytes while curl to the same host runs at full speed. The filtered ICMP replies leave the kernel retransmitting a segment the path cannot carry, which reads as a slow network rather than a broken one. --- docs/dev/microvm-local.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/dev/microvm-local.md b/docs/dev/microvm-local.md index 653002bd7c..67a211bbed 100644 --- a/docs/dev/microvm-local.md +++ b/docs/dev/microvm-local.md @@ -145,7 +145,8 @@ Linux-only libraries), so run it in the Lima guest, not on macOS: limactl shell docker-nested # Inside the VM — install build deps once: -sudo apt-get update && sudo apt-get install -y git pkg-config libcap-ng-dev libseccomp-dev zstd +sudo add-apt-repository ppa:git-core/ppa +sudo apt-get update && sudo apt-get install -y git build-essential pkg-config libcap-ng-dev libseccomp-dev zstd curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # rust via rustup source "$HOME/.cargo/env" @@ -191,4 +192,5 @@ requires a full guest boot and checkpoint. |---|---|---| | `/dev/kvm: permission denied` during the kind KVM probe | Rootless Docker: the probe container's root is remapped to your user, which can't open the device (`660 root:kvm`) | Use rootful Docker, or `sudo chmod 666 /dev/kvm` before `./hack/create-kind-cluster.sh` | | `cargo not found` from `assemble.sh` | On arm64, `virtiofsd` is built from source | Install the build deps listed in Option B, Step 3 | +| `assemble.sh` hangs on `cargo build`, then `spurious network error ... transfer too slow ... (transferred 0 bytes)`, while `curl` to the same host is fast | Path-MTU black hole: the path allows less than the guest's 1500-byte MTU, and the ICMP `fragmentation needed` replies are filtered, so the kernel keeps retransmitting a segment that cannot get through | `sudo sysctl -w net.ipv4.tcp_mtu_probing=1`, persisted in `/etc/sysctl.d/99-pmtu.conf` | | Lima: `[hostagent] Starting VZ ... FATA exiting` on M1/M2 | Apple's Virtualization framework supports nested virtualization only on M3 and later | Use an M3+ Mac, or a Linux/KVM host (Option A) |