From nobody Mon Feb 9 10:32:35 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510541; cv=none; d=zohomail.com; s=zohoarc; b=BSQZOZg0uQScy6Ypvw38oJ3k3IqEbPyNOo0NEoiFp+uhoYQEaxelAlkxikDHU46tKDy6DumkPib6VO/i5kxU0l4fssy9g5GtSPwKVDvYkPib3FRcqFH7ZMDbqDZJoAvJs8WtnhKjNqxVeS7jz8dwabTmuJcnHyodIgqhZbCnN14= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510541; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=NtjE9KVKdpTL6Tu8ZIhwb1HDmvJb+Qn445fVoY+1oBw=; b=jQPNolu8etkj1ZdhvqphY0oEHgmlX/qm3K1sBHIAm0902+HXy3x05zRs1FwFFiCcyqhHDm17rk9Ta8xTZni08GeC9w+hm4fCiiZEph5/hMbL7wF+0p2DdsG2tTMDVmMTAqKdPKI5tIFUsOsW1amJqie95h3vK3WGgAUgAkYDsQo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 1595510541044184.72503018144812; Thu, 23 Jul 2020 06:22:21 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-202-nVdrSt6MO22qtT7U73rceA-1; Thu, 23 Jul 2020 09:22:15 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 8F72B100CCC5; Thu, 23 Jul 2020 13:22:08 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 67E6D1059583; Thu, 23 Jul 2020 13:22:08 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 36A711800B71; Thu, 23 Jul 2020 13:22:08 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDM60G028492 for ; Thu, 23 Jul 2020 09:22:06 -0400 Received: by smtp.corp.redhat.com (Postfix) id 541451A922; Thu, 23 Jul 2020 13:22:06 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9C2091A91F for ; Thu, 23 Jul 2020 13:22:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510539; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=NtjE9KVKdpTL6Tu8ZIhwb1HDmvJb+Qn445fVoY+1oBw=; b=Qhm09U99cETAhICbM+eremhLJ3KYHWSiOaxJd7I+2/HkAHWAV/i7o76xV4eqqcFMuHuFRQ l3QuqwcWqmJnYp5AEWJOgTJh8N19L1ppur+4Ui/tSkqa7vwjoxLJ+G9V4xI0//m94Ko0KM lL9GNUaGdLruPMuawa+8ypvVBcXk1g0= X-MC-Unique: nVdrSt6MO22qtT7U73rceA-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 08/32] docs: formatdomain-devices: Split out Date: Thu, 23 Jul 2020 15:21:13 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Start splitting out part of into smaller sections. Signed-off-by: Peter Krempa --- 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-d= evices-filesystem.rst new file mode 100644 index 0000000000..4617a99fc5 --- /dev/null +++ b/docs/formatdomain-devices-filesystem.rst @@ -0,0 +1,169 @@ +:anchor:`` + +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` + +:: + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + ... + +``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=3D'path'`` or ``type=3D'handle'= `` + :since:`(since 0.9.7)` . The driver block has an optional attribute + ``wrpolicy`` that further controls interaction with the host page ca= che; + omitting the attribute gives default behavior, while the value + ``immediate`` means that a host writeback is immediately triggered f= or all + pages touched during a guest file write operation :since:`(since 0.9= .10)` + . :since:`Since 6.2.0` , ``type=3D'virtiofs'`` is also supported. Us= ing + virtiofs requires setting up shared memory, see the guide: + `Virtio-FS `__ + ``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 wil= l 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 e= lement + has a single attribute ``usage`` which gives the memory usage limit = in + KiB, unless units are specified by the ``units`` attribute. Only use= d by + LXC driver. :since:` (since 0.9.13)` + ``bind`` + A directory inside the guest will be bound to another directory insi= de 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=3D'mount'`` for the QEMU/KVM driv= er. 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 t= he + guest. This is the default ``accessmode`` if one is not specified. `= More + info `__ + ``mapped`` + The ``source`` is accessed with the permissions of the hypervisor (Q= EMU + process). `More + info `__ + ``squash`` + Similar to 'passthrough', the exception is that failure of privileged + operations like 'chown' are ignored. This makes a passthrough-like m= ode + usable for people who run the hypervisor as non-root. `More + info `__ + + :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 availa= ble + 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 with= out + encountering misbehaviours. Inode numbers from host are automatically + remapped on guest to actively prevent file ID collisions if guest ac= cesses + one export containing multiple devices. + ``forbid`` + Only allow to access one device per export by guest. Attempts to acc= ess + additional devices on the same export will cause the individual file= system + access by guest to fail with an error and being logged (once) as err= or 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 misbehaviou= rs 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 ca= se. + +``driver`` + The optional driver element allows specifying further details related t= o 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 ``forma= t`` + attribute provides the format type. For example, LXC supports a type= of + "loop", with a format of "raw" or "nbd" with any format. QEMU suppor= ts a + type of "path" or "handle", but no formats. Virtuozzo driver support= s 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 ``pat= h`` + can be used to override the path to the daemon. Attribute ``xattr`` ena= bles + 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 ``nam= e`` + attribute must be used with ``type=3D'template'``, and the ``dir`` attr= ibute + must be used with ``type=3D'mount'``. The ``usage`` attribute is used w= ith + ``type=3D'ram'`` to set the memory limit in KiB, unless units are speci= fied by + the ``units`` attribute. +``target`` + Where the ``source`` can be accessed in the guest. For most drivers thi= s 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.1= 3` +``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. Afterwa= rds + 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` .. include:: formatdomain-devices-disk.rst - -:anchor:`` - -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` - -:: - - ... - - - - - - - - - - - - - - - - - - - - - - - - - - - - ... - - ... - -``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=3D'path'`` or ``type=3D'handle'= `` - :since:`(since 0.9.7)` . The driver block has an optional attribute - ``wrpolicy`` that further controls interaction with the host page ca= che; - omitting the attribute gives default behavior, while the value - ``immediate`` means that a host writeback is immediately triggered f= or all - pages touched during a guest file write operation :since:`(since 0.9= .10)` - . :since:`Since 6.2.0` , ``type=3D'virtiofs'`` is also supported. Us= ing - virtiofs requires setting up shared memory, see the guide: - `Virtio-FS `__ - ``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 wil= l 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 e= lement - has a single attribute ``usage`` which gives the memory usage limit = in - KiB, unless units are specified by the ``units`` attribute. Only use= d by - LXC driver. :since:` (since 0.9.13)` - ``bind`` - A directory inside the guest will be bound to another directory insi= de 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=3D'mount'`` for the QEMU/KVM driv= er. 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 t= he - guest. This is the default ``accessmode`` if one is not specified. `= More - info `__ - ``mapped`` - The ``source`` is accessed with the permissions of the hypervisor (Q= EMU - process). `More - info `__ - ``squash`` - Similar to 'passthrough', the exception is that failure of privileged - operations like 'chown' are ignored. This makes a passthrough-like m= ode - usable for people who run the hypervisor as non-root. `More - info `__ - - :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 availa= ble - 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 with= out - encountering misbehaviours. Inode numbers from host are automatically - remapped on guest to actively prevent file ID collisions if guest ac= cesses - one export containing multiple devices. - ``forbid`` - Only allow to access one device per export by guest. Attempts to acc= ess - additional devices on the same export will cause the individual file= system - access by guest to fail with an error and being logged (once) as err= or 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 misbehaviou= rs 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 ca= se. - -``driver`` - The optional driver element allows specifying further details related t= o 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 ``forma= t`` - attribute provides the format type. For example, LXC supports a type= of - "loop", with a format of "raw" or "nbd" with any format. QEMU suppor= ts a - type of "path" or "handle", but no formats. Virtuozzo driver support= s 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 ``pat= h`` - can be used to override the path to the daemon. Attribute ``xattr`` ena= bles - 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 ``nam= e`` - attribute must be used with ``type=3D'template'``, and the ``dir`` attr= ibute - must be used with ``type=3D'mount'``. The ``usage`` attribute is used w= ith - ``type=3D'ram'`` to set the memory limit in KiB, unless units are speci= fied by - the ``units`` attribute. -``target`` - Where the ``source`` can be accessed in the guest. For most drivers thi= s 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.1= 3` -``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. Afterwa= rds - the hard limit is enforced. :since:`Since 0.9.13` +.. include:: formatdomain-devices-filesystem.rst :anchor:`` 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 =3D [ { 'name': 'formatdomain', 'includes': [ 'formatdomain-devices.rst', 'formatdomain-devices-disk.rst', + 'formatdomain-devices-filesystem.rst', ] }, { 'name': 'hacking' }, --=20 2.26.2