Add a document describing the usage of virtiofs.
---
 docs/kbase.html.in      |   3 +
 docs/kbase/virtiofs.rst | 152 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 155 insertions(+)
 create mode 100644 docs/kbase/virtiofs.rst

diff --git a/docs/kbase.html.in b/docs/kbase.html.in
index c156414c41..7d6caf3cb1 100644
--- a/docs/kbase.html.in
+++ b/docs/kbase.html.in
@@ -29,6 +29,9 @@
         <dt><a href="kbase/backing_chains.html">Backing chain management</a></dt>
         <dd>Explanation of how disk backing chain specification impacts libvirt's
           behaviour and basic troubleshooting steps of disk problems.</dd>
+
+        <dt><a href="kbase/virtiofs.html">Virtio-FS</a></dt>
+        <dd>Share a filesystem between the guest and the host</dd>
       </dl>
     </div>
 
diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst
new file mode 100644
index 0000000000..e76ff8ca4b
--- /dev/null
+++ b/docs/kbase/virtiofs.rst
@@ -0,0 +1,152 @@
+============================
+Sharing files with Virtio-FS
+============================
+
+=== 8< delete before merging 8< ===
+NOTE: if you're looking at this note, this is just a proposal.
+See the up-to-date version on: https://libvirt.org/kbase/virtiofs.html
+=== 8< --------------------- 8< ===
+
+.. contents::
+
+=========
+Virtio-FS
+=========
+
+Virtio-FS is a shared file system that lets virtual machines access
+a directory tree on the host. Unlike existing approaches, it
+is designed to offer local file system semantics and performance.
+
+See https://virtio-fs.gitlab.io/
+
+==========
+Host setup
+==========
+
+The host-side virtiofsd daemon, like other vhost-user backed devices,
+requres shared memory between the host and the guest. As of QEMU 4.2, this
+requires specifying a NUMA topology for the guest and explicitly specifying
+a memory backend. Multiple options are available:
+
+Either of the following:
+
+\a) Use file-backed memory
+
+Configure the directory where the files backing the memory will be stored
+with the ``memory_backing_dir`` option in ``/etc/libvirt/qemu.conf``
+
+::
+
+   # This directory is used for memoryBacking source if configured as file.
+   # NOTE: big files will be stored here
+   memory_backing_dir = "/dev/shm/"
+
+\b) Use hugepage-backed memory
+
+Make sure there are enough huge pages allocated for the requested guest memory.
+For example, for one guest with 2 GiB of RAM backed by 2 MiB hugepages:
+
+::
+
+   # virsh allocpages 2M 1024
+
+===========
+Guest setup
+===========
+
+\1. Specify the NUMA topology
+
+in the domain XML of the guest.
+For the simplest one-node topology for a guest with 2GiB of RAM and 8 vCPUs:
+
+::
+
+   <domain>
+     ...
+     <cpu ...>
+       <numa>
+         <cell id='0' cpus='0-7' memory='2' unit='GiB' memAccess='shared'/>
+       </numa>
+     </cpu>
+     ...
+   </domain>
+
+Note that the CPU element might already be specified and only one is allowed.
+
+\2. Specify the memory backend
+
+Either of the following:
+
+\2. a) File-backed memory
+
+::
+
+   <domain>
+     ...
+     <memoryBacking>
+       <access mode='shared'/>
+     </memoryBacking>
+     ...
+   </domain>
+
+This will create a file in the directory specified in ``qemu.conf``
+
+\2. b) Hugepage-backed memory
+
+::
+
+   <domain>
+     ...
+     <memoryBacking>
+       <hugepages>
+         <page size='2' unit='M'/>
+       </hugepages>
+       <access mode='shared'/>
+     </memoryBacking>
+     ...
+   </domain>
+
+\3. Add the ``vhost-user-fs`` QEMU device via the ``filesystem`` element
+
+::
+
+   <domain>
+     ...
+     <devices>
+       ...
+       <filesystem type='mount' accessmode='passthrough'>
+         <driver type='virtiofs'/>
+         <source dir='/path'/>
+         <target dir='mount_tag'/>
+       </filesystem>
+       ...
+     </devices>
+   </domain>
+
+Note that despite its name, the ``target dir`` is actually a mount tag and does
+not have to correspond to the desired mount point in the guest.
+
+So far, ``passthrough`` is the only supported access mode and it requires
+running the ``virtiofsd`` daemon as root.
+
+\4. Boot the guest and mount the filesystem
+
+::
+
+   guest# mount -t virtiofs mount_tag /mnt/mount/path
+
+Note: this requires virtiofs support in the guest kernel (Linux v5.4 or later)
+
+===================
+Optional parameters
+===================
+
+More optional elements can be specified
+
+::
+
+  <driver type='virtiofs' queue='1024'/>
+  <binary path='/usr/libexec/virtiofsd' xattr='on'>
+    <cache mode='always'/>
+    <lock posix_lock='on' flock='on'/>
+  </binary>
-- 
2.21.0

On Thu, Jan 30, 2020 at 06:06:20PM +0100, Ján Tomko wrote:
> Add a document describing the usage of virtiofs.
> ---
>  docs/kbase.html.in      |   3 +
>  docs/kbase/virtiofs.rst | 152 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 155 insertions(+)
>  create mode 100644 docs/kbase/virtiofs.rst
> 
> diff --git a/docs/kbase.html.in b/docs/kbase.html.in
> index c156414c41..7d6caf3cb1 100644
> --- a/docs/kbase.html.in
> +++ b/docs/kbase.html.in
> @@ -29,6 +29,9 @@
>          <dt><a href="kbase/backing_chains.html">Backing chain management</a></dt>
>          <dd>Explanation of how disk backing chain specification impacts libvirt's
>            behaviour and basic troubleshooting steps of disk problems.</dd>
> +
> +        <dt><a href="kbase/virtiofs.html">Virtio-FS</a></dt>
> +        <dd>Share a filesystem between the guest and the host</dd>
>        </dl>
>      </div>
>  
> diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst
> new file mode 100644
> index 0000000000..e76ff8ca4b
> --- /dev/null
> +++ b/docs/kbase/virtiofs.rst
> @@ -0,0 +1,152 @@
> +============================
> +Sharing files with Virtio-FS
> +============================
> +
> +=== 8< delete before merging 8< ===
> +NOTE: if you're looking at this note, this is just a proposal.
> +See the up-to-date version on: https://libvirt.org/kbase/virtiofs.html
> +=== 8< --------------------- 8< ===

...this shouldn't be here still

> +
> +.. contents::
> +
> +=========
> +Virtio-FS
> +=========
> +
> +Virtio-FS is a shared file system that lets virtual machines access
> +a directory tree on the host. Unlike existing approaches, it
> +is designed to offer local file system semantics and performance.
> +
> +See https://virtio-fs.gitlab.io/
> +
> +==========
> +Host setup
> +==========
> +
> +The host-side virtiofsd daemon, like other vhost-user backed devices,
> +requres shared memory between the host and the guest. As of QEMU 4.2, this

requires

> +requires specifying a NUMA topology for the guest and explicitly specifying
> +a memory backend. Multiple options are available:
> +
> +Either of the following:
> +
> +\a) Use file-backed memory

Why are you disabling list-ification here & throughout the file ?

> +
> +Configure the directory where the files backing the memory will be stored
> +with the ``memory_backing_dir`` option in ``/etc/libvirt/qemu.conf``
> +
> +::
> +
> +   # This directory is used for memoryBacking source if configured as file.
> +   # NOTE: big files will be stored here
> +   memory_backing_dir = "/dev/shm/"
> +
> +\b) Use hugepage-backed memory
> +
> +Make sure there are enough huge pages allocated for the requested guest memory.
> +For example, for one guest with 2 GiB of RAM backed by 2 MiB hugepages:
> +
> +::
> +
> +   # virsh allocpages 2M 1024


I'm not understanding from this how big the files will be for
virtiofsd ?  How much memory should users expect to be needed
per-guest per-virtiofsd ?



Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Mon, Feb 03, 2020 at 04:17:31PM +0000, Daniel P. Berrangé wrote:
> On Thu, Jan 30, 2020 at 06:06:20PM +0100, Ján Tomko wrote:
> > Add a document describing the usage of virtiofs.
> > ---
> >  docs/kbase.html.in      |   3 +
> >  docs/kbase/virtiofs.rst | 152 ++++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 155 insertions(+)
> >  create mode 100644 docs/kbase/virtiofs.rst
> > 
> > diff --git a/docs/kbase.html.in b/docs/kbase.html.in
> > index c156414c41..7d6caf3cb1 100644
> > --- a/docs/kbase.html.in
> > +++ b/docs/kbase.html.in
> > @@ -29,6 +29,9 @@
> >          <dt><a href="kbase/backing_chains.html">Backing chain management</a></dt>
> >          <dd>Explanation of how disk backing chain specification impacts libvirt's
> >            behaviour and basic troubleshooting steps of disk problems.</dd>
> > +
> > +        <dt><a href="kbase/virtiofs.html">Virtio-FS</a></dt>
> > +        <dd>Share a filesystem between the guest and the host</dd>
> >        </dl>
> >      </div>
> >  
> > diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst
> > new file mode 100644
> > index 0000000000..e76ff8ca4b
> > --- /dev/null
> > +++ b/docs/kbase/virtiofs.rst
> > @@ -0,0 +1,152 @@
> > +============================
> > +Sharing files with Virtio-FS
> > +============================
> > +
> > +=== 8< delete before merging 8< ===
> > +NOTE: if you're looking at this note, this is just a proposal.
> > +See the up-to-date version on: https://libvirt.org/kbase/virtiofs.html
> > +=== 8< --------------------- 8< ===
> 
> ...this shouldn't be here still
> 
> > +
> > +.. contents::
> > +
> > +=========
> > +Virtio-FS
> > +=========
> > +
> > +Virtio-FS is a shared file system that lets virtual machines access
> > +a directory tree on the host. Unlike existing approaches, it
> > +is designed to offer local file system semantics and performance.
> > +
> > +See https://virtio-fs.gitlab.io/
> > +
> > +==========
> > +Host setup
> > +==========
> > +
> > +The host-side virtiofsd daemon, like other vhost-user backed devices,
> > +requres shared memory between the host and the guest. As of QEMU 4.2, this
> 
> requires
> 
> > +requires specifying a NUMA topology for the guest and explicitly specifying
> > +a memory backend. Multiple options are available:
> > +
> > +Either of the following:
> > +
> > +\a) Use file-backed memory
> 
> Why are you disabling list-ification here & throughout the file ?
> 
> > +
> > +Configure the directory where the files backing the memory will be stored
> > +with the ``memory_backing_dir`` option in ``/etc/libvirt/qemu.conf``
> > +
> > +::
> > +
> > +   # This directory is used for memoryBacking source if configured as file.
> > +   # NOTE: big files will be stored here
> > +   memory_backing_dir = "/dev/shm/"
> > +
> > +\b) Use hugepage-backed memory
> > +
> > +Make sure there are enough huge pages allocated for the requested guest memory.
> > +For example, for one guest with 2 GiB of RAM backed by 2 MiB hugepages:
> > +
> > +::
> > +
> > +   # virsh allocpages 2M 1024
> 
> 
> I'm not understanding from this how big the files will be for
> virtiofsd ?  How much memory should users expect to be needed
> per-guest per-virtiofsd ?

Oh, I realize on re-reading that this part of the docs is just about
the general setup of a file backed guest. So we're just talking about
guest RAM size here, virtiofsd isn't using this file backing for
anything else. IOW, ignore this comment.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Mon, Feb 03, 2020 at 04:17:31PM +0000, Daniel P. Berrangé wrote:
>On Thu, Jan 30, 2020 at 06:06:20PM +0100, Ján Tomko wrote:
>> Add a document describing the usage of virtiofs.
>> ---
>>  docs/kbase.html.in      |   3 +
>>  docs/kbase/virtiofs.rst | 152 ++++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 155 insertions(+)
>>  create mode 100644 docs/kbase/virtiofs.rst
>>
>> diff --git a/docs/kbase.html.in b/docs/kbase.html.in
>> index c156414c41..7d6caf3cb1 100644
>> --- a/docs/kbase.html.in
>> +++ b/docs/kbase.html.in
>> @@ -29,6 +29,9 @@
>>          <dt><a href="kbase/backing_chains.html">Backing chain management</a></dt>
>>          <dd>Explanation of how disk backing chain specification impacts libvirt's
>>            behaviour and basic troubleshooting steps of disk problems.</dd>
>> +
>> +        <dt><a href="kbase/virtiofs.html">Virtio-FS</a></dt>
>> +        <dd>Share a filesystem between the guest and the host</dd>
>>        </dl>
>>      </div>
>>
>> diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst
>> new file mode 100644
>> index 0000000000..e76ff8ca4b
>> --- /dev/null
>> +++ b/docs/kbase/virtiofs.rst
>> @@ -0,0 +1,152 @@
>> +============================
>> +Sharing files with Virtio-FS
>> +============================
>> +
>> +=== 8< delete before merging 8< ===
>> +NOTE: if you're looking at this note, this is just a proposal.
>> +See the up-to-date version on: https://libvirt.org/kbase/virtiofs.html
>> +=== 8< --------------------- 8< ===
>
>...this shouldn't be here still
>

The plan was to leave it in every version posted to the mailing list,
for anyone who might find it through the archives.

>> +
>> +.. contents::
>> +
>> +=========
>> +Virtio-FS
>> +=========
>> +
>> +Virtio-FS is a shared file system that lets virtual machines access
>> +a directory tree on the host. Unlike existing approaches, it
>> +is designed to offer local file system semantics and performance.
>> +
>> +See https://virtio-fs.gitlab.io/
>> +
>> +==========
>> +Host setup
>> +==========
>> +
>> +The host-side virtiofsd daemon, like other vhost-user backed devices,
>> +requres shared memory between the host and the guest. As of QEMU 4.2, this
>
>requires
>
>> +requires specifying a NUMA topology for the guest and explicitly specifying
>> +a memory backend. Multiple options are available:
>> +
>> +Either of the following:
>> +
>> +\a) Use file-backed memory
>
>Why are you disabling list-ification here & throughout the file ?
>

I could not get it to do what I want - it kept resetting to 1.

Jano