From 01e4053bef19f7dc0166b177415bd70bfeb8b583 Mon Sep 17 00:00:00 2001 From: Victor Vieux Date: Fri, 6 Mar 2026 12:09:16 -0800 Subject: [PATCH] docs: Add disk locking documentation Add docs/disk_locking.md explaining advisory OFD locking, the lock_granularity parameter, byte-range vs whole-file semantics, and fallback behavior. Signed-off-by: Victor Vieux --- docs/disk_locking.md | 61 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/disk_locking.md diff --git a/docs/disk_locking.md b/docs/disk_locking.md new file mode 100644 index 000000000..adb8956a0 --- /dev/null +++ b/docs/disk_locking.md @@ -0,0 +1,61 @@ +# Disk Image Locking + +Cloud Hypervisor places an advisory lock on each disk image opened via +`--disk` to prevent multiple instances from concurrently accessing the +same file. This avoids potential data corruption from overlapping writes. +Locks are advisory and require cooperating processes; a non-cooperating +process can still open and write to a locked file. Locking is host-local +and does not enforce coordination across multiple hosts. + +If the backing file resides on network storage, the storage system must +correctly translate or propagate OFD (Open File Description) locks across +the network to ensure that advisory locking semantics are preserved in a +multi-host environment. In the case of Linux, OFD locks are translated +into NFS locks by the NFS driver. + +The implementation uses Open File Description (OFD) locks (`F_OFD_SETLK`) +rather than traditional POSIX locks (`F_SETLK`). OFD locks are only +released when the last file descriptor referencing the open file +description is closed, preventing accidental early release. + +## Lock Granularity + +The `lock_granularity` parameter controls how the lock is placed on the +disk image: + +``` +--disk path=/foo.img,lock_granularity=byte-range +--disk path=/bar.img,lock_granularity=full +``` + +### `byte-range` (default) + +Locks the byte range `[0, physical_file_size)`. The physical file size +is evaluated once at startup; if the file grows after the lock is +acquired, the newly appended region is not covered by the lock. + +The file is protected against concurrent access by other instances of +Cloud Hypervisor. That's the only thing we can guarantee. + +#### Fallback to full + +One caveat is that if the physical size of the disk image cannot be +determined at startup (e.g. with certain vhost-user backends), Cloud +Hypervisor falls back to a whole-file lock regardless of the +`lock_granularity` setting, as a byte-range lock cannot be safely +computed without knowing the physical file size. + +### `full` + +Locks the entire file using the OFD whole-file semantic (`l_start=0`, +`l_len=0`). This may be needed in environments that depend on whole-file +lock semantics. Note that on some network storage backends, whole-file +OFD locks may be treated as mandatory rather than advisory, which can +cause external tools to fail when accessing the disk image. Lock +behavior may also vary across network filesystem implementations. + +## Disk Resizing + +Cloud Hypervisor supports live disk resizing. Currently, byte-range +locks are not updated. However, as a part of the file is still locked, +no new Cloud Hypervisor instance can open the disk image.