Skip to content

Commit 73c9361

Browse files
committed
feat(vm): add host bind mount support via virtiofs (libkrun)
Introduce host directory bind mounts for libkrun VM sandboxes using the virtiofs4 API with simplified permission semantics. The gateway accepts `enable_bind_mounts` in the `[openshell.drivers.vm]` TOML table and forwards it to the VM driver subprocess. Mounts are specified per-sandbox in driver_config.mounts[] with source, target, optional read_only (default: read-only), and an optional `type` that must be `bind`, so Docker and Podman bind entries (without `selinux_label`) parse unchanged. At sandbox validation the driver rejects mounts unless bind mounts are enabled and resource admission is disabled. It rejects GPU and other QEMU launches, sources with control characters, and more mounts than libkrun has interrupt lines for (32 on aarch64, 3 on x86_64), and checks targets against reserved VM-internal directories and each other (no nested targets). The QEMU check runs again once the launch backend is resolved. Host source directories are checked at provisioning, before image preparation, so a briefly missing source fails provisioning visibly instead of denying recovery of a persisted sandbox. Missing, inaccessible, symlinked, non-directory, and unreadable sources are rejected: libkrun does not follow a final symlink, and on macOS it panics during guest boot when it cannot open the share root. The driver generates virtiofs tags and always writes a guest-side manifest into the overlay disk, together with the init drop-ins, so an image-supplied manifest can never drive guest mounts. The launcher parses its tab-separated --vm-mount arguments from the right, so a source can never shift the tag or mode, and the driver logs each shared directory at launch. Guest init mounts the shares after every /sandbox ownership fixup and the init drop-ins, so recursive chowns never reach host files. It refuses targets that traverse symlinks in the image, hands newly created mount point parents under /sandbox to the sandbox user, and skips an empty manifest. krun_add_virtiofs4 is resolved optionally, so older libkrun runtimes still boot sandboxes without mounts. The kernel config lists CONFIG_FUSE_FS and CONFIG_VIRTIO_FS explicitly; the pinned libkrunfw base config already enables both. A vm_bind_mount e2e test checks a read-write share round-trips data with the host, accepts a new file, directory, and nested file that the host then sees, and that a read-only share rejects writes. libkrun on rootless Linux refuses file creation by a guest user whose UID/GID differ from its own, so the VM e2e gateway runs the sandbox as the gateway user there. It enables bind mounts like the Docker and Podman e2e gateways. The runtimes docs cover the mount limit, the symlink restriction, the guest-kernel exposure, and the rootless Linux UID/GID note. The debug-openshell-cluster skill lists VM bind mount checks. Signed-off-by: Florent Benoit <[email protected]>
1 parent 5e414ea commit 73c9361

16 files changed

Lines changed: 1271 additions & 15 deletions

File tree

‎crates/openshell-core/src/driver_mounts.rs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,8 @@ pub fn path_is_or_under(path: &Path, parent: &Path) -> bool {
239239
path == parent || path.starts_with(parent)
240240
}
241241

242-
fn paths_overlap(left: &Path, right: &Path) -> bool {
242+
/// Return true when either path is the other or contains it.
243+
pub fn paths_overlap(left: &Path, right: &Path) -> bool {
243244
path_is_or_under(left, right) || path_is_or_under(right, left)
244245
}
245246

‎crates/openshell-driver-vm/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@ Select the VM driver with `--compute-driver vm`, `OPENSHELL_COMPUTE_DRIVER=vm`,
174174
| `proxy_connect_by_hostname` | unset | Send hostnames rather than validated IPs in CONNECT. Last resort for proxies whose ACLs reject IP CONNECT targets. |
175175
| `proxy_ca_bundle` | unset | Gateway-host PEM CA bundle trusted for the corporate proxy and TLS-intercepted server certificates. The driver validates it and stages it at a fixed non-secret guest path in the protected overlay. Requires `https_proxy`. |
176176
| `provider_spiffe_workload_api_tcp_endpoint` | unset | Explicit guest-reachable `tcp:IP:port` SPIFFE Workload API listener for provider token exchange. It requires `provider_spiffe_allow_guest_tcp = true`; a host UNIX socket is never silently exposed to a VM guest. |
177+
| `enable_bind_mounts` | `false` | Allow per-sandbox `driver_config.vm.mounts` host directory shares (libkrun virtiofs only). The driver writes a `tag\ttarget\tmode` manifest to `/.openshell/mounts.manifest` in the overlay, and guest init mounts each share after `/sandbox` ownership fixups. Rejected while resource admission is enabled. |
177178
178179
The proxy settings are operator-owned and deployment-level: they are not accepted through `template.driver_config.vm`, and the driver passes them only to native host control. Every present-but-invalid value is fatal at gateway or sandbox startup rather than degrading to a direct dial.
179180

‎crates/openshell-driver-vm/runtime/kernel/openshell.kconfig‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ CONFIG_VIRTIO_BLK=y
1515
CONFIG_EXT4_FS=y
1616
CONFIG_EXT4_USE_FOR_EXT2=y
1717

18+
# Host-directory sharing via virtiofs (used for VM driver bind mounts).
19+
# The pinned libkrunfw base config already enables both; they are listed here
20+
# because bind mounts depend on them.
21+
CONFIG_FUSE_FS=y
22+
CONFIG_VIRTIO_FS=y
23+
1824
# Cgroups used for process supervision and resource limits.
1925
CONFIG_CGROUPS=y
2026
CONFIG_CGROUP_DEVICE=y

‎crates/openshell-driver-vm/scripts/openshell-vm-sandbox-init.sh‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -544,6 +544,74 @@ run_openshell_init_dropins() {
544544
done < <(LC_ALL=C sort -u "$manifest")
545545
}
546546

547+
# Create a virtiofs mount point under ROOT_PREFIX without following symlinks,
548+
# so an image cannot redirect a validated target onto another guest path.
549+
# Directories created under /sandbox are handed to the sandbox user.
550+
prepare_virtiofs_target() {
551+
local target="$1" owner="$2"
552+
local path="${ROOT_PREFIX:-}" component
553+
local -a components
554+
IFS=/ read -r -a components <<<"${target#/}"
555+
for component in "${components[@]}"; do
556+
[ -n "$component" ] || continue
557+
path="${path}/${component}"
558+
if [ -L "$path" ]; then
559+
ts >&2 "FATAL: virtiofs mount target ${target} traverses symlink ${path#"${ROOT_PREFIX:-}"}"
560+
exit 1
561+
fi
562+
if [ ! -e "$path" ]; then
563+
if ! mkdir "$path"; then
564+
ts >&2 "FATAL: failed to create virtiofs mount point ${target}"
565+
exit 1
566+
fi
567+
case "${path#"${ROOT_PREFIX:-}"}" in
568+
/sandbox/*)
569+
if ! chown "$owner" "$path"; then
570+
ts >&2 "FATAL: failed to hand virtiofs mount point parent ${path#"${ROOT_PREFIX:-}"} to ${owner}"
571+
exit 1
572+
fi
573+
;;
574+
esac
575+
elif [ ! -d "$path" ]; then
576+
ts >&2 "FATAL: virtiofs mount target ${target} is not a directory"
577+
exit 1
578+
fi
579+
done
580+
printf '%s\n' "$path"
581+
}
582+
583+
# Runs after every /sandbox ownership fixup and the root-run init drop-ins so
584+
# nothing in init walks into host-backed shares.
585+
mount_virtiofs_shares() {
586+
local manifest
587+
manifest="$(root_path /.openshell/mounts.manifest)"
588+
# The driver always writes the manifest; it is empty without mounts.
589+
[ -s "$manifest" ] || return 0
590+
591+
ts "mounting virtiofs shares"
592+
local tag target mode mount_opts guest_target owner
593+
owner="$(sandbox_owner)"
594+
while IFS=$'\t' read -r tag target mode; do
595+
[ -n "$tag" ] || continue
596+
case "$mode" in
597+
ro) mount_opts="-o ro" ;;
598+
rw) mount_opts="" ;;
599+
*)
600+
ts "FATAL: unknown virtiofs mount mode '${mode}' for tag ${tag}"
601+
exit 1
602+
;;
603+
esac
604+
guest_target="$(prepare_virtiofs_target "$target" "$owner")" || exit 1
605+
# shellcheck disable=SC2086
606+
if mount -t virtiofs $mount_opts "$tag" "$guest_target"; then
607+
ts " mounted virtiofs ${tag} -> ${target} (${mode})"
608+
else
609+
ts "FATAL: failed to mount virtiofs ${tag} at ${target}"
610+
exit 1
611+
fi
612+
done < "$manifest"
613+
}
614+
547615
run_post_overlay_setup() {
548616
# Source QEMU-injected environment variables if present. The file lives in
549617
# the overlay upperdir so the cached bootstrap rootfs remains immutable.
@@ -617,6 +685,8 @@ fi
617685

618686
run_openshell_init_dropins
619687

688+
mount_virtiofs_shares
689+
620690
if [ -n "${OPENSHELL_SANDBOX_ID:-}" ]; then
621691
ts "OPENSHELL_SANDBOX_ID=${OPENSHELL_SANDBOX_ID}"
622692
fi

0 commit comments

Comments
 (0)