[PATCH 08/32] docs: formatdomain-devices: Split out <filesystem>

Start splitting out part of <devices> into smaller sections. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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