[libvirt] [PATCH 0/4] doc: storage.html updates
Hello, some documentation updates for new storage pools and volumes. Philipp Hahn (4): doc: document new storage volume/pool types doc: add storage format entries doc: fix writing of QEMU doc: white space changes docs/storage.html.in | 40 +++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) -- 1.7.10.4
Add qed for dirfs pool. Add ocfs2 for disk pool. Add lvm2 for disk and logical pool. Add cifs and glusterfs for netfs pool. Note: POOL_DISK_LVM2 can not be created by "parted mklabel", but is only returned from auto-detection on disk pools. Signed-off-by: Philipp Hahn <hahn@univention.de> --- docs/storage.html.in | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/storage.html.in b/docs/storage.html.in index 26a949a..92d7842 100644 --- a/docs/storage.html.in +++ b/docs/storage.html.in @@ -153,6 +153,7 @@ <li><code>iso</code>: CDROM disk image format</li> <li><code>qcow</code>: QEMU v1 disk image format</li> <li><code>qcow2</code>: QEMU v2 disk image format</li> + <li><code>qed</code>: QEMU Enhanced Disk image format</li> <li><code>vmdk</code>: VMWare disk image format</li> <li><code>vpc</code>: VirtualPC disk image format</li> </ul> @@ -229,6 +230,9 @@ <li> <code>xfs</code> </li> + <li> + <code>ocfs2</code> + </li> </ul> <h3>Valid volume format types</h3> @@ -269,6 +273,12 @@ <li> <code>nfs</code> </li> + <li> + <code>glusterfs</code> + </li> + <li> + <code>cifs</code> + </li> </ul> <h3>Valid volume format types</h3> @@ -304,8 +314,13 @@ <h3>Valid pool format types</h3> <p> - The logical volume pool does not use the pool format type element. + The logical volume pool supports the following formats: </p> + <ul> + <li><code>auto</code> - automatically determine format</li> + <li> + <code>lvm2</code> + </li> <h3>Valid volume format types</h3> <p> @@ -361,6 +376,9 @@ <li> <code>sun</code> </li> + <li> + <code>lvm2</code> + </li> </ul> <p> The <code>dos</code> or <code>gpt</code> formats are recommended for -- 1.7.10.4
On 02/26/2013 05:41 AM, Philipp Hahn wrote:
Add qed for dirfs pool. Add ocfs2 for disk pool. Add lvm2 for disk and logical pool. Add cifs and glusterfs for netfs pool.
Note: POOL_DISK_LVM2 can not be created by "parted mklabel", but is only returned from auto-detection on disk pools.
Signed-off-by: Philipp Hahn <hahn@univention.de> --- docs/storage.html.in | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-)
ACK, and I will push before 1.0.3. -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On 02/26/2013 05:56 PM, Eric Blake wrote:
On 02/26/2013 05:41 AM, Philipp Hahn wrote:
Add qed for dirfs pool. Add ocfs2 for disk pool. Add lvm2 for disk and logical pool. Add cifs and glusterfs for netfs pool.
Note: POOL_DISK_LVM2 can not be created by "parted mklabel", but is only returned from auto-detection on disk pools.
Signed-off-by: Philipp Hahn <hahn@univention.de> --- docs/storage.html.in | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-)
ACK, and I will push before 1.0.3.
Actually, this failed to build: Validating storage.html storage.html.tmp:535: element ul: validity error : Element ul content does not follow the DTD, expecting (li)+, got (li li h3 p h2 p h3) </ul> ^ I made the appropriate tweak: diff --git i/docs/storage.html.in w/docs/storage.html.in index 92d7842..756d4b9 100644 --- i/docs/storage.html.in +++ w/docs/storage.html.in @@ -321,6 +321,7 @@ <li> <code>lvm2</code> </li> + </ul> <h3>Valid volume format types</h3> <p> -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
Add format/@type entries to examples to show what the text is talking about. Signed-off-by: Philipp Hahn <hahn@univention.de> --- docs/storage.html.in | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/storage.html.in b/docs/storage.html.in index 92d7842..930d603 100644 --- a/docs/storage.html.in +++ b/docs/storage.html.in @@ -185,6 +185,7 @@ <name>virtimages</name> <source> <device path="/dev/VolGroup00/VirtImages"/> + <format type="auto"/> </source> <target> <path>/var/lib/virt/images</path> @@ -258,6 +259,7 @@ <source> <host name="nfs.example.com"/> <dir path="/var/lib/virt/images"/> + <format type="auto"/> </source> <target> <path>/var/lib/virt/images</path> @@ -306,6 +308,7 @@ <device path="/dev/sda1"/> <device path="/dev/sdb1"/> <device path="/dev/sdc1"/> + <format type="lvm2"/> </source> <target> <path>/dev/HostVG</path> @@ -343,6 +346,7 @@ <name>sda</name> <source> <device path='/dev/sda'/> + <format type='gpt'/> </source> <target> <path>/dev</path> -- 1.7.10.4
On 02/26/2013 05:42 AM, Philipp Hahn wrote:
Add format/@type entries to examples to show what the text is talking about.
Signed-off-by: Philipp Hahn <hahn@univention.de> --- docs/storage.html.in | 4 ++++ 1 file changed, 4 insertions(+)
+++ b/docs/storage.html.in @@ -185,6 +185,7 @@ <name>virtimages</name> <source> <device path="/dev/VolGroup00/VirtImages"/> + <format type="auto"/> </source>
Question - is type="auto" safe, or does it risk the CVE where a raw image can be abused by a guest in a manner to make libvirt mis-detect the storage as some other type, and potentially causing libvirt to follow a backing chain outside of the guest's permitted reach? Depending on the answer, either this is safe to push as-is into 1.0.3, or we should revisit all mention of type="auto" to clarify the danger of relying on probing. -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
Hello Eric, Am Mittwoch 27 Februar 2013, 02:00:07 schrieb Eric Blake:
On 02/26/2013 05:42 AM, Philipp Hahn wrote:
Add format/@type entries to examples to show what the text is talking about.
Signed-off-by: Philipp Hahn <hahn@univention.de> ---
docs/storage.html.in | 4 ++++ 1 file changed, 4 insertions(+)
+++ b/docs/storage.html.in @@ -185,6 +185,7 @@
<name>virtimages</name> <source>
<device path="/dev/VolGroup00/VirtImages"/>
+ <format type="auto"/>
</source>
Question - is type="auto" safe, or does it risk the CVE where a raw image can be abused by a guest in a manner to make libvirt mis-detect the storage as some other type, and potentially causing libvirt to follow a backing chain outside of the guest's permitted reach?
Good question! I just re-checked the three additions of <format type="auto"/> which all happen for storage pool, not storage volumes. So they are not accessible by VMs.
Depending on the answer, either this is safe to push as-is into 1.0.3, or we should revisit all mention of type="auto" to clarify the danger of relying on probing.
The "auto" are also the default from src/conf/storage_conf.c: $ grep -n "defaultFormat = VIR_STORAGE_POOL_" src/conf/storage_conf.c 152: .defaultFormat = VIR_STORAGE_POOL_LOGICAL_LVM2, 167: .defaultFormat = VIR_STORAGE_POOL_FS_AUTO, 181: .defaultFormat = VIR_STORAGE_POOL_NETFS_AUTO, 239: .defaultFormat = VIR_STORAGE_POOL_DISK_UNKNOWN, I chose "auto" because that looked like a safe default, before any admin accidentally wipes his pools. For the disk pool I chose "gpt" because "unknown" somehow looked strange and "msdos" is limited to 2 TB, so the seconds recommendation looked best to me. To me "auto" looks safe. Sincerely Philipp -- Philipp Hahn Open Source Software Engineer hahn@univention.de Univention GmbH be open. fon: +49 421 22 232- 0 Mary-Somerville-Str.1 D-28359 Bremen fax: +49 421 22 232-99 http://www.univention.de/
QEMU should be written all upper case. Signed-off-by: Philipp Hahn <hahn@univention.de> --- docs/storage.html.in | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/storage.html.in b/docs/storage.html.in index 930d603..8391f85 100644 --- a/docs/storage.html.in +++ b/docs/storage.html.in @@ -524,13 +524,13 @@ This storage driver provides a pool which contains all RBD images in a RADOS pool. RBD (RADOS Block Device) is part of the Ceph distributed storage project.<br/> - This backend <i>only</i> supports Qemu with RBD support. Kernel RBD + This backend <i>only</i> supports QEMU with RBD support. Kernel RBD which exposes RBD devices as block devices in /dev is <i>not</i> supported. RBD images created with this storage backend can be accessed through kernel RBD if configured manually, but this backend does not provide mapping for these images.<br/> - Images created with this backend can be attached to Qemu guests - when Qemu is build with RBD support (Since Qemu 0.14.0). The + Images created with this backend can be attached to QEMU guests + when QEMU is build with RBD support (Since QEMU 0.14.0). The backend supports cephx authentication for communication with the Ceph cluster. Storing the cephx authentication key is done with the libvirt secret mechanism. The UUID in the example pool input @@ -574,7 +574,7 @@ </volume></pre> <h3>Example disk attachement</h3> - <p>RBD images can be attached to Qemu guests when Qemu is built + <p>RBD images can be attached to QEMU guests when QEMU is built with RBD support. Information about attaching a RBD image to a guest can be found at <a href="formatdomain.html#elementsDisks">format domain</a> @@ -633,7 +633,7 @@ </volume></pre> <h3>Example disk attachment</h3> - <p>Sheepdog images can be attached to Qemu guests. + <p>Sheepdog images can be attached to QEMU guests. Information about attaching a Sheepdog image to a guest can be found at the <a href="formatdomain.html#elementsDisks">format domain</a> -- 1.7.10.4
use two blank line before the next <h2>, which helps reading the source file. I find the html file still hard to read as there is no clear separation between different storage pool types. Some CSS tweaks would be appreciated. Signed-off-by: Philipp Hahn <hahn@univention.de> --- docs/storage.html.in | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/storage.html.in b/docs/storage.html.in index 8391f85..14eba20 100644 --- a/docs/storage.html.in +++ b/docs/storage.html.in @@ -115,6 +115,7 @@ </li> </ul> + <h2><a name="StorageBackendDir">Directory pool</a></h2> <p> A pool with a type of <code>dir</code> provides the means to manage @@ -165,7 +166,6 @@ either <code>qemu-img</code> or <code>qcow-create</code> tools are present. The others are dependent on support of the <code>qemu-img</code> tool. - </p> <h2><a name="StorageBackendFS">Filesystem pool</a></h2> @@ -455,6 +455,7 @@ The iSCSI volume pool does not use the volume format type element. </p> + <h2><a name="StorageBackendSCSI">SCSI volume pools</a></h2> <p> This provides a pool based on a SCSI HBA. Volumes are preexisting SCSI @@ -487,6 +488,7 @@ The SCSI volume pool does not use the volume format type element. </p> + <h2><a name="StorageBackendMultipath">Multipath pools</a></h2> <p> This provides a pool that contains all the multipath devices on the @@ -519,6 +521,7 @@ The Multipath volume pool does not use the volume format type element. </p> + <h2><a name="StorageBackendRBD">RBD pools</a></h2> <p> This storage driver provides a pool which contains all RBD @@ -590,6 +593,7 @@ The RBD pool does not use the volume format type element. </p> + <h2><a name="StorageBackendSheepdog">Sheepdog pools</a></h2> <p> This provides a pool based on a Sheepdog Cluster. -- 1.7.10.4
participants (2)
-
Eric Blake -
Philipp Hahn