[pve-devel] [PATCH docs v7 3/11] added shared filesystem doc for virtio-fs

[Fabian Grünbichler]

On August 9, 2023 10:37 am, Markus Frank wrote:
> Signed-off-by: Markus Frank <m.frank at proxmox.com>
> ---
>  qm.adoc | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 68 insertions(+), 2 deletions(-)
> 
> diff --git a/qm.adoc b/qm.adoc
> index e35dbf0..8f4020d 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -997,6 +997,71 @@ recommended to always use a limiter to avoid guests using too many host
>  resources. If desired, a value of '0' for `max_bytes` can be used to disable
>  all limits.
>  
> +[[qm_virtiofs]]
> +Virtio-fs
> +~~~~~~~~~
> +
> +Virtio-fs is a shared file system, that enables sharing a directory between
> +host and guest VM while taking advantage of the locality of virtual machines
> +and the hypervisor to get a higher throughput than 9p.
> +
> +Linux VMs with kernel >=5.4 support this feature by default.
> +
> +There is a guide available on how to utilize virtiofs in Windows VMs.
> +https://github.com/virtio-win/kvm-guest-drivers-windows/wiki/Virtiofs:-Shared-file-system
> +
> +Add mapping for Shared Directories
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +To add a mapping, go to the Resource Mapping tab in Datacenter in the WebUI,
> +use the API directly with pvesh as described in the
> +xref:resource_mapping[Resource Mapping] section,
> +or add the mapping to the configuration file `/etc/pve/mapping/dir.cfg`:
> +
> +----
> +some-dir-id
> +    map node=node1,path=/mnt/share/,submounts=1
> +    map node=node2,path=/mnt/share/,
> +    xattr 1
> +    acl 1
> +----
> +
> +Set `submounts` to `1` when multiple file systems are mounted in a
> +shared directory.
> +
> +Add virtiofs to VM
> +^^^^^^^^^^^^^^^^^^
> +
> +To share a directory using virtio-fs, you need to specify the directory ID
> +(dirid) that has been configured in the Resource Mapping. Additionally, you
> +can set the `cache` option to either `always`, `never`, or `auto`, depending on
> +your requirements. If you want virtio-fs to honor the `O_DIRECT` flag, you can
> +set the `direct-io` parameter to `1`.
> +Additionally it possible to overwrite the default mapping settings
> +for xattr & acl by setting then to either `1` or `0`.
> +
> +The `acl` parameter automatically implies `xattr`, that is, it makes no
> +difference whether you set xattr to `0` if acl is set to `1`.
> +
> +----
> +qm set <vmid> -virtiofs0 dirid=<dirid>,tag=<mount tag>,cache=always,direct-io=1
> +qm set <vmid> -virtiofs1 <dirid>,tag=<mount tag>,cache=never,xattr=1
> +qm set <vmid> -virtiofs2 <dirid>,tag=<mount tag>,acl=1

nit: the mount tag is not settable anymore in this version

some more caveats and limitations would be nice in the docs IMHO!

> +----
> +
> +To mount virtio-fs in a guest VM with the Linux kernel virtiofs driver, run the
> +following command:
> +
> +The dirid associated with the path on the current node is also used as the
> +mount tag (name used to mount the device on the guest).
> +
> +----
> +mount -t virtiofs <mount tag> <mount point>
> +----
> +
> +For more information on available virtiofsd parameters, see the
> +https://gitlab.com/virtio-fs/virtiofsd[GitLab virtiofsd project page].
> +
>  [[qm_bootorder]]
>  Device Boot Order
>  ~~~~~~~~~~~~~~~~~
> @@ -1600,8 +1665,9 @@ in the relevant tab in the `Resource Mappings` category, or on the cli with
>  # pvesh create /cluster/mapping/<type> <options>
>  ----
>  
> -Where `<type>` is the hardware type (currently either `pci` or `usb`) and
> -`<options>` are the device mappings and other configuration parameters.
> +Where `<type>` is the hardware type (currently either `pci`, `usb` or
> +xref:qm_virtiofs[dir]) and `<options>` are the device mappings and other
> +configuration parameters.
>  
>  Note that the options must include a map property with all identifying
>  properties of that hardware, so that it's possible to verify the hardware did
> -- 
> 2.39.2
> 
> 
> 
> _______________________________________________
> pve-devel mailing list
> pve-devel at lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
> 
> 
>