[PATCH 08/32] docs: formatdomain-devices: Split out <filesystem>
Peter Krempa
pkrempa at redhat.com
Thu Jul 23 13:21:13 UTC 2020
Start splitting out part of <devices> into smaller sections.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatdomain-devices-filesystem.rst | 169 ++++++++++++++++++++++
docs/formatdomain-devices.rst | 171 +----------------------
docs/meson.build | 1 +
3 files changed, 171 insertions(+), 170 deletions(-)
create mode 100644 docs/formatdomain-devices-filesystem.rst
diff --git a/docs/formatdomain-devices-filesystem.rst b/docs/formatdomain-devices-filesystem.rst
new file mode 100644
index 0000000000..4617a99fc5
--- /dev/null
+++ b/docs/formatdomain-devices-filesystem.rst
@@ -0,0 +1,169 @@
+:anchor:`<a id="elementsFilesystems"/>`
+
+Filesystems
+~~~~~~~~~~~
+
+A directory on the host that can be accessed directly from the guest.
+:since:`since 0.3.3, since 0.8.5 for QEMU/KVM`
+
+::
+
+ ...
+ <devices>
+ <filesystem type='template'>
+ <source name='my-vm-template'/>
+ <target dir='/'/>
+ </filesystem>
+ <filesystem type='mount' accessmode='passthrough' multidevs='remap'>
+ <driver type='path' wrpolicy='immediate'/>
+ <source dir='/export/to/guest'/>
+ <target dir='/import/from/host'/>
+ <readonly/>
+ </filesystem>
+ <filesystem type='file' accessmode='passthrough'>
+ <driver type='loop' format='raw'/>
+ <driver type='path' wrpolicy='immediate'/>
+ <source file='/export/to/guest.img'/>
+ <target dir='/import/from/host'/>
+ <readonly/>
+ </filesystem>
+ <filesystem type='mount' accessmode='passthrough'>
+ <driver type='virtiofs' queue='1024'/>
+ <binary path='/usr/libexec/virtiofsd' xattr='on'>
+ <cache mode='always'/>
+ <lock posix='on' flock='on'/>
+ </binary>
+ <source dir='/path'/>
+ <target dir='mount_tag'/>
+ </filesystem>
+ ...
+ </devices>
+ ...
+
+``filesystem``
+ The filesystem attribute ``type`` specifies the type of the ``source``. The
+ possible values are:
+
+ ``mount``
+ A host directory to mount in the guest. Used by LXC, OpenVZ :since:`(since
+ 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``type``
+ if one is not specified. This mode also has an optional sub-element
+ ``driver``, with an attribute ``type='path'`` or ``type='handle'``
+ :since:`(since 0.9.7)` . The driver block has an optional attribute
+ ``wrpolicy`` that further controls interaction with the host page cache;
+ omitting the attribute gives default behavior, while the value
+ ``immediate`` means that a host writeback is immediately triggered for all
+ pages touched during a guest file write operation :since:`(since 0.9.10)`
+ . :since:`Since 6.2.0` , ``type='virtiofs'`` is also supported. Using
+ virtiofs requires setting up shared memory, see the guide:
+ `Virtio-FS <kbase/virtiofs.html>`__
+ ``template``
+ OpenVZ filesystem template. Only used by OpenVZ driver.
+ ``file``
+ A host file will be treated as an image and mounted in the guest. The
+ filesystem format will be autodetected. Only used by LXC driver.
+ ``block``
+ A host block device to mount in the guest. The filesystem format will be
+ autodetected. Only used by LXC driver :since:`(since 0.9.5)` .
+ ``ram``
+ An in-memory filesystem, using memory from the host OS. The source element
+ has a single attribute ``usage`` which gives the memory usage limit in
+ KiB, unless units are specified by the ``units`` attribute. Only used by
+ LXC driver. :since:` (since 0.9.13)`
+ ``bind``
+ A directory inside the guest will be bound to another directory inside the
+ guest. Only used by LXC driver :since:` (since 0.9.13)`
+
+ The filesystem element has an optional attribute ``accessmode`` which
+ specifies the security mode for accessing the source :since:`(since 0.8.5)` .
+ Currently this only works with ``type='mount'`` for the QEMU/KVM driver. For
+ driver type ``virtiofs``, only ``passthrough`` is supported. For other driver
+ types, the possible values are:
+
+ ``passthrough``
+ The ``source`` is accessed with the permissions of the user inside the
+ guest. This is the default ``accessmode`` if one is not specified. `More
+ info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
+ ``mapped``
+ The ``source`` is accessed with the permissions of the hypervisor (QEMU
+ process). `More
+ info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
+ ``squash``
+ Similar to 'passthrough', the exception is that failure of privileged
+ operations like 'chown' are ignored. This makes a passthrough-like mode
+ usable for people who run the hypervisor as non-root. `More
+ info <http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html>`__
+
+ :since:`Since 5.2.0` , the filesystem element has an optional attribute
+ ``model`` with supported values "virtio-transitional",
+ "virtio-non-transitional", or "virtio". See `Virtio transitional
+ devices <#elementsVirtioTransitional>`__ for more details.
+
+ The filesystem element has an optional attribute ``multidevs`` which
+ specifies how to deal with a filesystem export containing more than one
+ device, in order to avoid file ID collisions on guest when using 9pfs (
+ :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not available
+ for virtiofs. The possible values are:
+
+ ``default``
+ Use QEMU's default setting (which currently is ``warn``).
+ ``remap``
+ This setting allows guest to access multiple devices per export without
+ encountering misbehaviours. Inode numbers from host are automatically
+ remapped on guest to actively prevent file ID collisions if guest accesses
+ one export containing multiple devices.
+ ``forbid``
+ Only allow to access one device per export by guest. Attempts to access
+ additional devices on the same export will cause the individual filesystem
+ access by guest to fail with an error and being logged (once) as error on
+ host side.
+ ``warn``
+ This setting resembles the behaviour of 9pfs prior to QEMU 4.2, that is no
+ action is performed to prevent any potential file ID collisions if an
+ export contains multiple devices, with the only exception: a warning is
+ logged (once) on host side now. This setting may lead to misbehaviours on
+ guest side if more than one device is exported per export, due to the
+ potential file ID collisions this may cause on guest side in that case.
+
+``driver``
+ The optional driver element allows specifying further details related to the
+ hypervisor driver used to provide the filesystem. :since:`Since 1.0.6`
+
+ - If the hypervisor supports multiple backend drivers, then the ``type``
+ attribute selects the primary backend driver name, while the ``format``
+ attribute provides the format type. For example, LXC supports a type of
+ "loop", with a format of "raw" or "nbd" with any format. QEMU supports a
+ type of "path" or "handle", but no formats. Virtuozzo driver supports a
+ type of "ploop" with a format of "ploop".
+ - For virtio-backed devices, `Virtio-specific options <#elementsVirtio>`__
+ can also be set. ( :since:`Since 3.5.0` )
+ - For ``virtiofs``, the ``queue`` attribute can be used to specify the queue
+ size (i.e. how many requests can the queue fit). ( :since:`Since 6.2.0` )
+
+``binary``
+ The optional ``binary`` element can tune the options for virtiofsd. All of
+ the following attributes and elements are optional. The attribute ``path``
+ can be used to override the path to the daemon. Attribute ``xattr`` enables
+ the use of filesystem extended attributes. Caching can be tuned via the
+ ``cache`` element, possible ``mode`` values being ``none`` and ``always``.
+ Locking can be controlled via the ``lock`` element - attributes ``posix`` and
+ ``flock`` both accepting values ``on`` or ``off``. ( :since:`Since 6.2.0` )
+``source``
+ The resource on the host that is being accessed in the guest. The ``name``
+ attribute must be used with ``type='template'``, and the ``dir`` attribute
+ must be used with ``type='mount'``. The ``usage`` attribute is used with
+ ``type='ram'`` to set the memory limit in KiB, unless units are specified by
+ the ``units`` attribute.
+``target``
+ Where the ``source`` can be accessed in the guest. For most drivers this is
+ an automatic mount point, but for QEMU/KVM this is merely an arbitrary string
+ tag that is exported to the guest as a hint for where to mount.
+``readonly``
+ Enables exporting filesystem as a readonly mount for guest, by default
+ read-write access is given (currently only works for QEMU/KVM driver).
+``space_hard_limit``
+ Maximum space available to this guest's filesystem. :since:`Since 0.9.13`
+``space_soft_limit``
+ Maximum space available to this guest's filesystem. The container is
+ permitted to exceed its soft limits for a grace period of time. Afterwards
+ the hard limit is enforced. :since:`Since 0.9.13`
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index a004ad42f9..564ce4caca 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -40,176 +40,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
</devices>
.. include:: formatdomain-devices-disk.rst
-
-:anchor:`<a id="elementsFilesystems"/>`
-
-Filesystems
-~~~~~~~~~~~
-
-A directory on the host that can be accessed directly from the guest.
-:since:`since 0.3.3, since 0.8.5 for QEMU/KVM`
-
-::
-
- ...
- <devices>
- <filesystem type='template'>
- <source name='my-vm-template'/>
- <target dir='/'/>
- </filesystem>
- <filesystem type='mount' accessmode='passthrough' multidevs='remap'>
- <driver type='path' wrpolicy='immediate'/>
- <source dir='/export/to/guest'/>
- <target dir='/import/from/host'/>
- <readonly/>
- </filesystem>
- <filesystem type='file' accessmode='passthrough'>
- <driver type='loop' format='raw'/>
- <driver type='path' wrpolicy='immediate'/>
- <source file='/export/to/guest.img'/>
- <target dir='/import/from/host'/>
- <readonly/>
- </filesystem>
- <filesystem type='mount' accessmode='passthrough'>
- <driver type='virtiofs' queue='1024'/>
- <binary path='/usr/libexec/virtiofsd' xattr='on'>
- <cache mode='always'/>
- <lock posix='on' flock='on'/>
- </binary>
- <source dir='/path'/>
- <target dir='mount_tag'/>
- </filesystem>
- ...
- </devices>
- ...
-
-``filesystem``
- The filesystem attribute ``type`` specifies the type of the ``source``. The
- possible values are:
-
- ``mount``
- A host directory to mount in the guest. Used by LXC, OpenVZ :since:`(since
- 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``type``
- if one is not specified. This mode also has an optional sub-element
- ``driver``, with an attribute ``type='path'`` or ``type='handle'``
- :since:`(since 0.9.7)` . The driver block has an optional attribute
- ``wrpolicy`` that further controls interaction with the host page cache;
- omitting the attribute gives default behavior, while the value
- ``immediate`` means that a host writeback is immediately triggered for all
- pages touched during a guest file write operation :since:`(since 0.9.10)`
- . :since:`Since 6.2.0` , ``type='virtiofs'`` is also supported. Using
- virtiofs requires setting up shared memory, see the guide:
- `Virtio-FS <kbase/virtiofs.html>`__
- ``template``
- OpenVZ filesystem template. Only used by OpenVZ driver.
- ``file``
- A host file will be treated as an image and mounted in the guest. The
- filesystem format will be autodetected. Only used by LXC driver.
- ``block``
- A host block device to mount in the guest. The filesystem format will be
- autodetected. Only used by LXC driver :since:`(since 0.9.5)` .
- ``ram``
- An in-memory filesystem, using memory from the host OS. The source element
- has a single attribute ``usage`` which gives the memory usage limit in
- KiB, unless units are specified by the ``units`` attribute. Only used by
- LXC driver. :since:` (since 0.9.13)`
- ``bind``
- A directory inside the guest will be bound to another directory inside the
- guest. Only used by LXC driver :since:` (since 0.9.13)`
-
- The filesystem element has an optional attribute ``accessmode`` which
- specifies the security mode for accessing the source :since:`(since 0.8.5)` .
- Currently this only works with ``type='mount'`` for the QEMU/KVM driver. For
- driver type ``virtiofs``, only ``passthrough`` is supported. For other driver
- types, the possible values are:
-
- ``passthrough``
- The ``source`` is accessed with the permissions of the user inside the
- guest. This is the default ``accessmode`` if one is not specified. `More
- info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
- ``mapped``
- The ``source`` is accessed with the permissions of the hypervisor (QEMU
- process). `More
- info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
- ``squash``
- Similar to 'passthrough', the exception is that failure of privileged
- operations like 'chown' are ignored. This makes a passthrough-like mode
- usable for people who run the hypervisor as non-root. `More
- info <http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html>`__
-
- :since:`Since 5.2.0` , the filesystem element has an optional attribute
- ``model`` with supported values "virtio-transitional",
- "virtio-non-transitional", or "virtio". See `Virtio transitional
- devices <#elementsVirtioTransitional>`__ for more details.
-
- The filesystem element has an optional attribute ``multidevs`` which
- specifies how to deal with a filesystem export containing more than one
- device, in order to avoid file ID collisions on guest when using 9pfs (
- :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not available
- for virtiofs. The possible values are:
-
- ``default``
- Use QEMU's default setting (which currently is ``warn``).
- ``remap``
- This setting allows guest to access multiple devices per export without
- encountering misbehaviours. Inode numbers from host are automatically
- remapped on guest to actively prevent file ID collisions if guest accesses
- one export containing multiple devices.
- ``forbid``
- Only allow to access one device per export by guest. Attempts to access
- additional devices on the same export will cause the individual filesystem
- access by guest to fail with an error and being logged (once) as error on
- host side.
- ``warn``
- This setting resembles the behaviour of 9pfs prior to QEMU 4.2, that is no
- action is performed to prevent any potential file ID collisions if an
- export contains multiple devices, with the only exception: a warning is
- logged (once) on host side now. This setting may lead to misbehaviours on
- guest side if more than one device is exported per export, due to the
- potential file ID collisions this may cause on guest side in that case.
-
-``driver``
- The optional driver element allows specifying further details related to the
- hypervisor driver used to provide the filesystem. :since:`Since 1.0.6`
-
- - If the hypervisor supports multiple backend drivers, then the ``type``
- attribute selects the primary backend driver name, while the ``format``
- attribute provides the format type. For example, LXC supports a type of
- "loop", with a format of "raw" or "nbd" with any format. QEMU supports a
- type of "path" or "handle", but no formats. Virtuozzo driver supports a
- type of "ploop" with a format of "ploop".
- - For virtio-backed devices, `Virtio-specific options <#elementsVirtio>`__
- can also be set. ( :since:`Since 3.5.0` )
- - For ``virtiofs``, the ``queue`` attribute can be used to specify the queue
- size (i.e. how many requests can the queue fit). ( :since:`Since 6.2.0` )
-
-``binary``
- The optional ``binary`` element can tune the options for virtiofsd. All of
- the following attributes and elements are optional. The attribute ``path``
- can be used to override the path to the daemon. Attribute ``xattr`` enables
- the use of filesystem extended attributes. Caching can be tuned via the
- ``cache`` element, possible ``mode`` values being ``none`` and ``always``.
- Locking can be controlled via the ``lock`` element - attributes ``posix`` and
- ``flock`` both accepting values ``on`` or ``off``. ( :since:`Since 6.2.0` )
-``source``
- The resource on the host that is being accessed in the guest. The ``name``
- attribute must be used with ``type='template'``, and the ``dir`` attribute
- must be used with ``type='mount'``. The ``usage`` attribute is used with
- ``type='ram'`` to set the memory limit in KiB, unless units are specified by
- the ``units`` attribute.
-``target``
- Where the ``source`` can be accessed in the guest. For most drivers this is
- an automatic mount point, but for QEMU/KVM this is merely an arbitrary string
- tag that is exported to the guest as a hint for where to mount.
-``readonly``
- Enables exporting filesystem as a readonly mount for guest, by default
- read-write access is given (currently only works for QEMU/KVM driver).
-``space_hard_limit``
- Maximum space available to this guest's filesystem. :since:`Since 0.9.13`
-``space_soft_limit``
- Maximum space available to this guest's filesystem. The container is
- permitted to exceed its soft limits for a grace period of time. Afterwards
- the hard limit is enforced. :since:`Since 0.9.13`
+.. include:: formatdomain-devices-filesystem.rst
:anchor:`<a id="elementsAddress"/>`
diff --git a/docs/meson.build b/docs/meson.build
index fb9bd18ee3..e4e7cf4c89 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -125,6 +125,7 @@ docs_rst_files = [
{ 'name': 'formatdomain',
'includes': [ 'formatdomain-devices.rst',
'formatdomain-devices-disk.rst',
+ 'formatdomain-devices-filesystem.rst',
]
},
{ 'name': 'hacking' },
--
2.26.2
More information about the libvir-list
mailing list