1# How to use virtio-fs 2 3In the context of virtualization, it is always convenient to be able to share a 4directory from the host with the guest. 5 6__virtio-fs__, also known as __vhost-user-fs__ is a virtual device defined by 7the VIRTIO specification which allows any VMM to perform filesystem sharing. 8 9## Pre-requisites 10 11### The daemon 12 13This virtual device relies on the _vhost-user_ protocol, which assumes the 14backend (device emulation) is handled by a dedicated process running on the 15host. This daemon is called __virtiofsd__ and needs to be present on the host. 16 17_Build virtiofsd_ 18```bash 19git clone https://gitlab.com/virtio-fs/virtiofsd 20pushd virtiofsd 21cargo build --release 22sudo setcap cap_sys_admin+epi target/release/virtiofsd 23``` 24 25_Create shared directory_ 26```bash 27mkdir /tmp/shared_dir 28``` 29_Run virtiofsd_ 30```bash 31./virtiofsd \ 32 -d \ 33 --socket-path=/tmp/virtiofs \ 34 --shared-dir=/tmp/shared_dir \ 35 --cache=never 36``` 37 38The `cache=never` option is the default when using `virtiofsd` with 39Cloud Hypervisor. This prevents from using the host page cache, reducing the 40overall footprint on host memory. This increases the maximum density of virtual 41machines that can be launched on a single host. 42 43The `cache=always` option will allow the host page cache to be used, which can 44result in better performance for the guest's workload at the cost of increasing 45the footprint on host memory. 46 47### Kernel support 48 49Modern Linux kernels (at least v5.10) have support for virtio-fs. Use of older 50kernels, with additional patches, are not supported. 51 52## How to share directories with cloud-hypervisor 53 54### Start the VM 55 56Once the daemon is running, the option `--fs` from Cloud Hypervisor needs 57to be used. 58 59Both direct kernel boot and EFI firmware can be used to boot a VM with 60virtio-fs, given that the cloud image contains a recent enough kernel. 61 62Correct functioning of `--fs` requires `--memory shared=on` to facilitate 63interprocess memory sharing. 64 65Assuming you have `focal-server-cloudimg-amd64.raw` and `vmlinux` on your 66system, here is the Cloud Hypervisor command you need to run: 67```bash 68./cloud-hypervisor \ 69 --cpus boot=1 \ 70 --memory size=1G,shared=on \ 71 --disk path=focal-server-cloudimg-amd64.raw \ 72 --kernel vmlinux \ 73 --cmdline "console=hvc0 root=/dev/vda1 rw" \ 74 --fs tag=myfs,socket=/tmp/virtiofs,num_queues=1,queue_size=512 75``` 76 77### Mount the shared directory 78 79The last step is to mount the shared directory inside the guest, using the 80`virtiofs` filesystem type. 81 82```bash 83mkdir mount_dir 84mount -t virtiofs myfs mount_dir/ 85``` 86 87The `tag` needs to be consistent with what has been provided through the 88Cloud Hypervisor command line, which happens to be `myfs` in this example. 89 90## DAX feature 91 92Given the DAX feature is not stable yet from a daemon standpoint, it is not 93available in Cloud Hypervisor.