Note the implications and caveats of <disk type='dir'>.

Closes: https://gitlab.com/libvirt/libvirt/-/issues/519
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
 docs/formatdomain.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index cd9cb02bf8..9787933d4d 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -2634,6 +2634,12 @@ paravirtualized driver is specified via the ``disk`` element.
        </source>
        <target dev='sdb' bus='scsi'/>
      </disk>
+     <disk type='dir' device='floppy'>
+       <driver name='qemu' type='fat'/>
+       <source dir='/var/somefiles'>
+       <target dev='fda'/>
+       <readonly/>
+     </disk>
      <disk type='volume' device='disk'>
        <driver name='qemu' type='raw'/>
        <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/>
@@ -2757,6 +2763,18 @@ paravirtualized driver is specified via the ``disk`` element.
    ``dir``
       The ``dir`` attribute specifies the fully-qualified path to the directory
       to use as the disk. :since:`Since 0.7.5`
+
+      Note that most hypervisors that support ``dir`` disks do that by exposing
+      an emulated block device with an emulated filesystem populated with
+      contents of the configured directory. As guest operating system may cache
+      the filesystem metadata, outside changes to the directory may not appear
+      in the guest and/or may result in corrupted data being observable from
+      the VM.
+
+      The format of the emulated filesystem is controlled by the ``format``
+      attribute of the ``<driver>`` driver element. Currently only the ``fat``
+      format is supported. Hypervisors may only support ``<readonly/>`` mode.
+
    ``network``
       The ``protocol`` attribute specifies the protocol to access to the
       requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdog",
-- 
2.41.0

On a Friday in 2023, Peter Krempa wrote:
>Note the implications and caveats of <disk type='dir'>.
>
>Closes: https://gitlab.com/libvirt/libvirt/-/issues/519
>Signed-off-by: Peter Krempa <pkrempa@redhat.com>
>---
> docs/formatdomain.rst | 18 ++++++++++++++++++
> 1 file changed, 18 insertions(+)
>

Reviewed-by: Ján Tomko <jtomko@redhat.com>

Jano

On Fri, Aug 25, 2023 at 02:34:04PM +0200, Peter Krempa wrote:
> Note the implications and caveats of <disk type='dir'>.
> 
> Closes: https://gitlab.com/libvirt/libvirt/-/issues/519
> Signed-off-by: Peter Krempa <pkrempa@redhat.com>
> ---
>  docs/formatdomain.rst | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)

Reviewed-by: Pavel Hrdina <phrdina@redhat.com>