Fs

Crosvm supports virtio-fs, a shared file system that lets virtual machines access a directory tree on the host. It allows the guest to access files on the host machine. This section will explain how to create a shared directory. You can also find a runnable sample in tools/examples/example_fs.

Creating a Shared Directory on the Host Machine

To create a shared directory, run the following commands in the host machine:

mkdir host_shared_dir
HOST_SHARED_DIR=$(pwd)/host_shared_dir
crosvm run \
   --shared-dir "$HOST_SHARED_DIR:my_shared_tag:type=fs" \
  ... # usual crosvm args

In the --shared-dir argument:

• The first field is the directory to be shared ($HOST_SHARED_DIR in this example).
• The second field is the tag that the VM will use to identify the device (my_shared_tag in this example).
• The remaining fields are key-value pairs configuring the shared directory.

To see available options, run crosvm run --help.

Mount the Shared Directory in the Guest OS

Next, switch to the guest OS and run the following commands to set up the shared directory:

sudo su
mkdir /tmp/guest_shared_dir
mount -t virtiofs my_shared_tag /tmp/guest_shared_dir

You can now add files to the shared directory. Any files you put in the guest_shared_dir will appear in the host_shared_dir on the host machine, and vice versa.

Running VirtioFS as root filesystem

It is also possible to boot crosvm directly from a virtio-fs directory, as long as the directory structure matches that of a valid rootfs. The outcome is similar to running a chroot but inside a VM.

Running VMs with virtio-fs as root filesystem may not be ideal as performance will not be as good as running a root disk with virtio-block, but it can be useful to run tests and debug while sharing files between host and guest.

You can refer to the advanced usage page for the instructions on how to run virtio-fs as rootfs.

Dynamic Path Allowlist

Crosvm supports dynamically updating the path allowlist for virtio-fs at runtime via a Unix domain socket. This allows host-side processes to grant or revoke access to specific paths in the shared directory after the VM has started.

To enable this feature, start the vhost-user-fs device with the --allowlist-socket-path option:

crosvm device fs \
  --allowlist-socket-path /path/to/allowlist.sock \
  --tag my_shared_tag \
  --shared-dir /path/to/share \
  --socket-path /path/to/vhost.sock

Wire Protocol

The control socket communicates using JSON-serialized structured messages over SOCK_SEQPACKET.

All paths specified in the commands must be relative to the shared directory root, starting with /. For example, if the shared directory is /path/to/share on the host, and you want to allow access to /path/to/share/foo/bar, you must specify /foo/bar in the command.

Request Format

Requests are sent as JSON objects representing the FsAllowlistCommand enum.

• Add Paths: Add one or more paths to the allowlist.

  {
    "AddPaths": {
      "paths": ["/path/in/shared/dir", "/another/path"]
    }
  }
  

• Remove Paths: Remove one or more paths from the allowlist.

  {
    "RemovePaths": {
      "paths": ["/path/in/shared/dir"]
    }
  }
  

Response Format

Responses are JSON objects representing the FsAllowlistResponse enum.

• Success:

  "Ok"
  

• Error:

  {
    "Err": "Detailed error message"
  }