[pve-devel] [PATCH docs v6 1/1] added shared filesystem doc for virtio-fs

[Christoph Heiss]

w.r.t the subject line: s/added/add/, should not be past-tense

As mentioned in the cover letter reply, a sentence explaining what the
mount tag is and about the virtio/WinFsp drivers situation would also be
useful.

On Thu, Jul 06, 2023 at 12:54:13PM +0200, Markus Frank wrote:
>
> Signed-off-by: Markus Frank <m.frank at proxmox.com>
> ---
>  qm.adoc | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 58 insertions(+), 2 deletions(-)
>
> diff --git a/qm.adoc b/qm.adoc
> index e35dbf0..00a0668 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -997,6 +997,61 @@ 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.
Maybe add a sentence about availability/compatibility? E.g. it is
supported since Linux 5.4 from what I could quickly gather. Minimum
virtio drivers version for Windows would also be useful, I guess. There
are always some people who try to run some ancient software.

> +The parameter `hugepages` must be disabled to use virtio-fs.
This can probably be reworded a bit, to make it clear that this means
the VM configuration parameter.

Something like e.g.: "This feature is incompatible with the hugepages
feature. The `hugepages` VM configuration option must thus be
disabled if virtio-fs is to be used."

> +
> +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:
nit: The path should be surrounded with backticks for monospacing

> +
> +----
> +some-dir-id
> +	map node=node1,path=/share/,xattr=1,acl=1,submounts=1
> +	map node=node2,path=/share/,xattr=1
> +	map node=node3,path=/different-share-path/,submounts=1
> +	map node=node4,path=/foobar/
> +	map node=node5,path=/somewhere/,acl=1
> +----
> +
> +The Parameter `acl` automatically implies `xattr`, so there would be no need to
nit:   ^^^^^^^^^ should be lowercase

> +set `xattr` for node1 in this example.
> +Set `submounts` to `1` when using multiple file systems in the shared directory.
> +
> +Add virtiofs to VM
> +^^^^^^^^^^^^^^^^^^
> +
> +To share a directory with virtio-fs, you need to specify the directory ID
nit: s/with/using/      ^^^^

> +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`.
> +
> +----
> +qm set <vmid> -virtiofs0 dirid=<dirid>,tag=<mount tag>,cache=always,direct-io=1
> +qm set <vmid> -virtiofs1 <dirid>,tag=<mount tag>,cache=never
> +qm set <vmid> -virtiofs2 <dirid>,tag=<mount tag>
> +----
> +
> +To mount virtio-fs in a guest VM with the Linux kernel virtiofs driver, run the
> +following command:
> +
> +----
> +mount -t virtiofs <mount tag> <mount point>
> +----
> +
> +For more information on the virtiofsd parameters, see:
Maybe better written like:

"For more information on available virtiofsd parameters, see the
https://gitlab.com/virtio-fs/virtiofsd[GitLab project page]."

> +https://gitlab.com/virtio-fs/virtiofsd[GitLab virtiofsd]
> +
>  [[qm_bootorder]]
>  Device Boot Order
>  ~~~~~~~~~~~~~~~~~
> @@ -1600,8 +1655,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
>
>