From 60fb587470ba2cd7a86b54cdfc0b1fb99c531643 Mon Sep 17 00:00:00 2001 From: Christophe Fergeau Date: Thu, 2 Nov 2023 13:53:58 +0100 Subject: [PATCH] doc: Document sparse/cow images with APFS --- doc/quickstart.md | 1 + doc/usage.md | 26 +++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/doc/quickstart.md b/doc/quickstart.md index a15fc56a..3d010142 100644 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -100,6 +100,7 @@ This allows to lookup the IP which was assigned to the virtual machine by search Once you have a virtual machine up and running, here are some additional features which can be useful: +- [sparse/copy-on-write disk images](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#thin-images) - [host/guest communication over virtio-vsock](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#virtio-vsock-communication) - [host/guest file sharing with virtio-fs](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#file-sharing) - [Rosetta support to run x86_64 binaries in virtual machines on Apple silicon Macs](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#rosetta) diff --git a/doc/usage.md b/doc/usage.md index 6414b4e5..d3a94aaa 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -119,9 +119,33 @@ Various devices can be added to the virtual machines. They are all paravirtualiz #### Description The `--device virtio-blk` option adds a disk to the virtual machine. The disk is backed by an image file on the host machine. This file is a raw image file. -This means an empty 1GiB disk can be created with `dd if=/dev/zero of=vfkit.img bs=1G count=1`. See also [vz/CreateDiskImage](https://pkg.go.dev/github.com/Code-Hex/vz/v3#CreateDiskImage). + +#### Thin images + +Apple Virtualization Framework only support raw disk images and ISO images. +There is no support for thin image formats such as [qcow2](https://en.wikipedia.org/wiki/Qcow). + +However, APFS, the default macOS filesystem has support for sparse files and copy-on-write files, so it offers the main features of thin image format. + +A sparse raw image can be created/expanded using the `truncate` command or +using +[`truncate(2)`](https://manpagez.com/man/2/truncate/). +For example, an empty 1GiB disk can be created with `truncate --size 1G +vfkit.img`. Such an image will only use disk space when content is written to +it. It initially only uses a few bytes of actual disk space even if it's size +is 1G. + +A copy-on-write image is a raw image file which references a backing file. Its +initial content is the same as its backing file, and the data is shared with +the backing file. This means the copy-on-write image does not use extra disk +space when it's created. When this image is modified, the changes will only be +made to the copy-on-write image, and not to the backing file. Only the +modified data will use actual disk space. +A copy-on-write image can be created using `cp -c` or [clonefile(2)](http://www.manpagez.com/man/2/clonefile/). + + #### Arguments - `path`: the absolute path to the disk image file. - `deviceId`: `/dev/disk/by-id/` identifier to use for this device.