External/cloud-hypervisor
1
0
Fork 0
mirror of https://github.com/cloud-hypervisor/cloud-hypervisor.git synced 2024-10-02 11:35:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update virtio-fs documentation

Browse Source 
Update the content of the documentation to clarify how the cache option
from virtiofsd has an impact on the host page cache, while the dax
option for the filesystem in the guest has an impact on the guest page
cache.

The document is also updated to not have lines exceeding 80 characters.

Fixes #3826

Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
This commit is contained in:
Sebastien Boeuf 2022-03-17 17:48:03 +01:00
parent 86f8fb1c70
commit 2dc9cfaf01
1 changed files with 49 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
docs/fs.md
View File

@ -1,14 +1,18 @@
# How to use virtio-fs
In the context of virtualization, it is always convenient to be able to share a directory from the host with the guest.
In the context of virtualization, it is always convenient to be able to share a
directory from the host with the guest.
__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.
__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.
## Pre-requisites
### The daemon
This 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.
This 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.
_Build virtiofsd_
```bash
@ -31,25 +35,35 @@ _Run virtiofsd_
--cache=never
```
The `cache=never` 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.
The `cache=never` option is the default when using `virtiofsd` with
Cloud Hypervisor. This prevents from using the host page cache, reducing the
overall footprint on host memory. This increases the maximum density of virtual
machines that can be launched on a single host.
The `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.
The `cache=always` option will allow the host page cache to be used, which can
result in better performance for the guest's workload at the cost of increasing
the footprint on host memory.
### Kernel support
Modern Linux kernels starting (at least v5.10) have support for virtio-fs. Use
of older kernels, with additional patches, are not supported.
Modern Linux kernels (at least v5.10) have support for virtio-fs. Use of older
kernels, with additional patches, are not supported.
## How to share directories with cloud-hypervisor
### Start the VM
Once the daemon is running, the option `--fs` from __cloud-hypervisor__ needs to be used.
Direct kernel boot is the preferred option, but we can boot from an EFI cloud image if it contains a recent enough kernel.
Once the daemon is running, the option `--fs` from Cloud Hypervisor needs
to be used.
Because _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.
Both direct kernel boot and EFI firmware can be used to boot a VM with
virtio-fs, given that the cloud image contains a recent enough kernel.
Assuming you have `focal-server-cloudimg-amd64.raw` and `vmlinux` on your system, here is the __cloud-hypervisor__ command you need to run:
Correct functioning of `--fs` requires `--memory shared=on` to facilitate
interprocess memory sharing.
Assuming you have `focal-server-cloudimg-amd64.raw` and `vmlinux` on your
system, here is the Cloud Hypervisor command you need to run:
```bash
./cloud-hypervisor \
--cpus boot=1 \
@ -60,14 +74,18 @@ Assuming you have `focal-server-cloudimg-amd64.raw` and `vmlinux` on your system
--fs tag=myfs,socket=/tmp/virtiofs,num_queues=1,queue_size=512
```
By 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:
By 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:
```bash
--fs tag=myfs,socket=/tmp/virtiofs,num_queues=1,queue_size=512,dax=on,cache_size=4G
```
In 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.
In 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.
```bash
--fs tag=myfs,socket=/tmp/virtiofs,num_queues=1,queue_size=512,dax=off
@ -75,11 +93,26 @@ In case you don't want to use a shared window of cache to pass the shared files
```
### Mount the shared directory
The last step is to mount the shared directory inside the guest, using the `virtiofs` filesystem type.
The last step is to mount the shared directory inside the guest, using the
`virtiofs` filesystem type.
```bash
mkdir mount_dir
mount -t virtiofs -o dax myfs mount_dir/
```
The `tag` needs to be consistent with what has been provided through the __cloud-hypervisor__ command line, which happens to be `myfs` in this example.
The `-o dax` option must be removed in case the shared cache region is not enabled from the VMM.
The `tag` needs to be consistent with what has been provided through the
Cloud Hypervisor command line, which happens to be `myfs` in this example.
The `-o dax` option must be removed in case the shared cache region is not
enabled from the VMM.
The filesystem should be mounted with `dax` by default as it bypasses the guest
page cache, reducing the footprint on host memory. 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.
When the filesystem is not mounted with the `dax` option, the guest page cache
is used, which can result in better performance for the guest's workload at the
cost of increasing the footprint on host memory.