From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id B90A391E72 for ; Wed, 31 Jan 2024 14:27:06 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 944A03B035 for ; Wed, 31 Jan 2024 14:26:36 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS for ; Wed, 31 Jan 2024 14:26:35 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id B422549324 for ; Wed, 31 Jan 2024 14:26:35 +0100 (CET) Message-ID: Date: Wed, 31 Jan 2024 14:26:34 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: Proxmox VE development discussion , Markus Frank References: <20231108085254.53574-1-m.frank@proxmox.com> <20231108085254.53574-4-m.frank@proxmox.com> From: Fiona Ebner In-Reply-To: <20231108085254.53574-4-m.frank@proxmox.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.073 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_SCC_BODY_TEXT_LINE -0.01 - Subject: Re: [pve-devel] [PATCH docs v8 3/7] added shared filesystem doc for virtio-fs X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 31 Jan 2024 13:27:06 -0000 IMHO the wording/word order with "shared filesystem doc" could be improved. It's the doc/section for the shared filesystem virtio-fs. Am 08.11.23 um 09:52 schrieb Markus Frank: > Signed-off-by: Markus Frank > --- > qm.adoc | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- > 1 file changed, 82 insertions(+), 2 deletions(-) > > diff --git a/qm.adoc b/qm.adoc > index c4f1024..571c42e 100644 > --- a/qm.adoc > +++ b/qm.adoc > @@ -996,6 +996,85 @@ 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 I think the comma should not be here > +host and guest VM while taking advantage of the locality of virtual machines Maybe split the sentence, e.g. "guest VM. It takes advantage" > +and the hypervisor to get a higher throughput than 9p. I'd say "the 9p remote file system protocol" so that people hearing it for the first time will have an idea too. > + > +To use virtio-fs, the https://gitlab.com/virtio-fs/virtiofsd[virtiofsd] daemon > +needs to run in the background. > +In {pve} this process starts immediately before the start of QEMU. I think there should be a comma after {pve}. My thesis advisor taught me the following trick that works in many cases: "If you can read it as a stand-alone sentence, there should be a comma." For example, the "there should be a comma" can be read as a stand-alone sentence ;) Nit: since it's the same paragraph, there should be no newline before this line. > + > +Linux VMs with kernel >=5.4 support this feature by default. > + > +There is a guide available on how to utilize virtio-fs in Windows VMs. > +https://github.com/virtio-win/kvm-guest-drivers-windows/wiki/Virtiofs:-Shared-file-system > + > +Known limitations L should be capitalized for title-case > +^^^^^^^^^^^^^^^^^ > + > +* Virtiofsd crashing means no recovery until VM is fully stopped > +and restarted. > +* Virtiofsd not responding may result in NFS-like hanging access in the VM. > +* Memory hotplug does not work in combination with virtio-fs. Out of interest: is this being worked on upstream, a fundamental design limitation or a limitation on our side? > +* Windows cannot understand ACLs. Therefore, disable it for Windows VMs, > +otherwise the virtio-fs device will not be visible within the VMs. If there is no corresponding warning for this in qemu-server yet, please add one > + > +Add mapping for Shared Directories M should be capitalized for title-case > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > + > +To add a mapping, either use the API directly with pvesh as described in the Since it's a CLI command s/pvesh/`pvesh`/ I'd be inclined to repeat, i.e. "a mapping for a shared directory," > +xref:resource_mapping[Resource Mapping] section, Style nit: no newline here > +or add the mapping to the configuration file `/etc/pve/mapping/dir.cfg`: I'd rather not suggest this. Manual editing will cause much more problems, because there are no checks. > + > +---- > +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. I suppose "and you want to make all available in the guest." > + > +Add virtio-fs to VM to a VM > +^^^^^^^^^^^^^^^^^^^ > + > +To share a directory using virtio-fs, you need to specify the directory ID > +(dirid) that has been configured in the Resource Mapping. Specify it where? Maybe start out with mentioning the configuration option, i.e. virtiofs and then what parameters it takes? "resource mapping" should not be capitalized > +Additionally, you can set the `cache` option to either `always`, `never`, Style nit: no newline before this line, it's the same paragraph > +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`. Please mention briefly what the implications for the different cache settings and the direct-io flag are and what the defaults are. > +Additionally it possible to overwrite the default mapping settings "Additionally, it is" > +for xattr & acl by setting then to either `1` or `0`. `xattr` and `acl` s/then/them/ > + > +The `acl` parameter automatically implies `xattr`, that is, it makes no > +difference whether you set xattr to `0` if acl is set to `1`. This should be mentioned in the description of the parameter in the schema too. Also, please use `xattr` and `acl` again. > + > +---- > +qm set -virtiofs0 dirid=,cache=always,direct-io=1 > +qm set -virtiofs1 ,cache=never,xattr=1 > +qm set -virtiofs2 ,acl=1 > +---- > + > +To mount virtio-fs in a guest VM with the Linux kernel virtio-fs driver, run the > +following command: "command inside the guest:" to reduce the number of users trying it on the host > + > +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). Style nit: Early newline, "mount" fits the 80 character limit