1# How to use virtio-fs 2 3In the context of virtualization, it is always convenient to be able to share a directory from the host with the guest. 4 5__virtio-fs__, also known as __vhost-user-fs__ is a virtual device defined by the VIRTIO specification which allows any VMM to perform filesystem sharing. 6 7## Pre-requisites 8 9### The daemon 10 11This virtual device relies on the _vhost-user_ protocol, which assumes the backend (device emulation) is handled by a dedicated process running on the host. This daemon is called __virtiofsd__ and needs to be present on the host. 12 13_Build virtiofsd_ 14```bash 15git clone --depth 1 "https://gitlab.com/virtio-fs/qemu.git" -b "qemu5.0-virtiofs-dax" $VIRTIOFSD_DIR 16cd $VIRTIOFSD_DIR 17./configure --prefix=$PWD --target-list=x86_64-softmmu 18make virtiofsd -j `nproc` 19sudo setcap cap_sys_admin+epi "virtiofsd" 20``` 21_Create shared directory_ 22```bash 23mkdir /tmp/shared_dir 24``` 25_Run virtiofsd_ 26```bash 27./virtiofsd \ 28 -d \ 29 --socket-path=/tmp/virtiofs \ 30 -o source=/tmp/shared_dir \ 31 -o cache=none 32``` 33 34The `cache=none` option should be the default when using `virtiofsd` with the __cloud-hypervisor__ VMM. This prevents from using the guest page cache, which reduces the memory footprint of the guest. When running multiple virtual machines on the same host, this will let the host deal with page cache, which will increase the density of virtual machines which can be launched. 35 36The `cache=always` option will allow for the guest page cache to be used, which will increase the memory footprint of the guest. This option should be used only for specific use cases where a single VM is going to be running on a host. 37 38### Kernel support 39 40Modern Linux kernels starting (at least v5.10) have support for virtio-fs. Use 41of older kernels, with additional patches, are not supported. 42 43## How to share directories with cloud-hypervisor 44 45### Start the VM 46Once the daemon is running, the option `--fs` from __cloud-hypervisor__ needs to be used. 47 48Direct kernel boot is the preferred option, but we can boot from an EFI cloud image if it contains a recent enough kernel. 49 50Because _vhost-user_ expects a dedicated process (__virtiofsd__ in this case) to be able to access the guest RAM to communicate through the _virtqueues_ with the driver running in the guest, `--memory` option needs to be slightly modified. It must specify `shared=on` to share the memory pages so that an external process can access them. 51 52Assuming you have `focal-server-cloudimg-amd64.raw` and `vmlinux` on your system, here is the __cloud-hypervisor__ command you need to run: 53```bash 54./cloud-hypervisor \ 55 --cpus boot=1 \ 56 --memory size=1G,shared=on \ 57 --disk path=focal-server-cloudimg-amd64.raw \ 58 --kernel vmlinux \ 59 --cmdline "console=hvc0 root=/dev/vda1 rw" \ 60 --fs tag=myfs,socket=/tmp/virtiofs,num_queues=1,queue_size=512 61``` 62 63By default, DAX is enabled with a cache window of 8GiB. You can specify a custom size (let's say 4GiB for this example) for the cache by explicitly setting DAX and the cache size: 64 65```bash 66--fs tag=myfs,socket=/tmp/virtiofs,num_queues=1,queue_size=512,dax=on,cache_size=4G 67 68``` 69 70In case you don't want to use a shared window of cache to pass the shared files content, this means you will have to explicitly disable DAX with `dax=off`. Note that in this case, the `cache_size` parameter will be ignored. 71 72```bash 73--fs tag=myfs,socket=/tmp/virtiofs,num_queues=1,queue_size=512,dax=off 74 75``` 76 77### Mount the shared directory 78The last step is to mount the shared directory inside the guest, using the `virtiofs` filesystem type. 79```bash 80mkdir mount_dir 81mount -t virtiofs -o dax myfs mount_dir/ 82``` 83The `tag` needs to be consistent with what has been provided through the __cloud-hypervisor__ command line, which happens to be `myfs` in this example. 84 85The `-o dax` option must be removed in case the shared cache region is not enabled from the VMM. 86