Support attaching /dev/diskN block devices on macOS VZ hosts

[pirate]

Fixes #1314 & #2224

📖 Wrote a blog post based on my learnings too: https://docs.sweeting.me/s/sockets-101

Summary

This adds VZ-only support on macOS for attaching host block devices to Lima VMs.

A VM can now be launched with:

limactl start --block-device=/dev/disk4 ...

It can also be configured in YAML with the top-level blockDevices field.

The attached device is exposed to the guest as a virtio block device, and Lima sets a deterministic block device identifier from the host basename. For example, /dev/disk4 appears in the guest under /dev/disk/by-id/virtio-disk4.

Implementation

• added the --block-device CLI flag and top-level blockDevices config support
• attached host block devices in the VZ driver with VZDiskBlockDeviceStorageDeviceAttachment
• kept block-device-specific VZ runtime logic in pkg/driver/vz/block_device_darwin.go
• added a hidden limactl sudo-open-block-device helper that opens a host block device and passes the file descriptor back to the unprivileged VM process
• kept the helper path backend-neutral in pkg/blockdevice
• moved generic sudo execution and sudoers rendering helpers into pkg/sudoers
• kept pkg/networks network-specific by limiting it to network sudoers entries and network validation
• updated limactl sudoers to compose the shared /etc/sudoers.d/lima file from network entries plus the block-device helper entry
• documented top-level blockDevices in templates/default.yaml and the disk docs
• non-VZ backends reject blockDevices explicitly for now

Layout Notes

The ownership boundaries are now:

• pkg/networks: network config, validation, and network-specific sudoers fragments
• pkg/sudoers: generic sudo invocation and sudoers file helpers
• pkg/blockdevice: generic block-device helper, request validation, fd handoff, and sudoers fragment
• pkg/driver/vz/block_device_darwin.go: VZ block-device attachment logic
• cmd/limactl sudoers: existing CLI command, combines network sudoers entries with blockdevice entries to create the final /etc/sudoers.d/lima file
• cmd/limactl sudo-open-block-device: small helper that runs as root to get a file descriptor for the block device before passing it to the still-rootless main Lima VM process

That keeps block-device support separate from network behavior while still reusing the same sudo helpers that both need.

Why

Opening /dev/disk* on macOS requires elevated privileges, but Lima generally avoids running its normal VM lifecycle as root. This change keeps that behavior intact by escalating only for the narrow helper that opens the requested block device and passes the file descriptor back to the unprivileged VZ process.

Adding this feature to Lima unlocks many use-cases around testing and using custom filesystem kernel modules, e.g. ZFS-in-lima on macOS hosts that don't have ZFS/macFUSE installed: https://github.com/pirate/zfsbox

Validation

Automated:

• go test ./pkg/limayaml ./cmd/limactl/editflags ./pkg/driver/qemu ./pkg/blockdevice ./pkg/sudoers ./pkg/networks
• go test -c ./pkg/driver/vz
• go test -c ./pkg/driver/krunkit
• go test -c ./cmd/limactl
• GOOS=windows GOARCH=amd64 go test -c ./pkg/driver/wsl2
• ./hack/bats/lib/bats-core/bin/bats --count ./hack/bats/extras/vz-block-device.bats

Live validation on macOS with VZ block-device roundtrip coverage:

• --block-device /dev/diskN roundtrip via BATS
• top-level blockDevices: YAML using /dev/rdiskN roundtrip via BATS
• both cases create a ramdisk, partition it as GPT, format it as exFAT, write from the guest, stop the VM, mount and read on the host, append on the host, restart, and read back in the guest

Round-trip writes succeed and the block device is usable as a normal drive in both OSs.

---

Related Links

• How to attach raw disk to lima vm instance? (USB) #1314
• USB passthrough rabbit hole #2224
• [POC] USB sharing with host #1317
• https://www.reddit.com/r/zfs/comments/1sqvqfd/zfsbox_run_zfs_in_a_small_vm_so_you_dont_need_to/oho1ef5/?context=3
• Feasibility of external drive passthrough as block device? utmapp/UTM#5921
• https://wiki.openstack.org/wiki/Raw-device-mapping-support
• https://old.reddit.com/r/VFIO/comments/4fjsie/howto_passing_through_an_entire_block_device/
• https://lima-vm.io/docs/config/mount/
• https://developer.apple.com/documentation/virtualization/vzdiskblockdevicestoragedeviceattachment

Next Steps

There are more VZ APIs we can wire up to forward things like /dev/tty0-usbmodem.sock, USB HCI devices, and more.

• https://developer.apple.com/documentation/virtualization/usb-devices
• https://developer.apple.com/documentation/virtualization/vznetworkblockdevicestoragedeviceattachment
• https://developer.apple.com/documentation/virtualization/vzvirtioblockdeviceconfiguration

[whoschek]

Very cool!
Would love to see functionality like this to enable backup to ZFS pools on external drives!

[AkihiroSuda]

Merge branch 'master' into vz-block-device-sharing

Please tidy up the commit messages
https://lima-vm.io/docs/dev/git/#squashing-commits

[AkihiroSuda]

Sorry, needs rebasing again

[AkihiroSuda]

Thanks