conf: Output disk backing store details in domain XML

The XML for quite a longish backing chain is shown below:

  <disk type='network' device='disk'>
    <driver name='qemu' type='qcow2'/>
    <source protocol='nbd' name='bar'>
      <host transport='unix' socket='/var/run/nbdsock'/>
    </source>
    <backingStore type='block' index='1'>
      <format type='qcow2'/>
      <source dev='/dev/HostVG/QEMUGuest1'/>
      <backingStore type='file' index='2'>
        <format type='qcow2'/>
        <source file='/tmp/image2.qcow'/>
        <backingStore type='file' index='3'>
          <format type='qcow2'/>
          <source file='/tmp/image3.qcow'/>
          <backingStore type='file' index='4'>
            <format type='qcow2'/>
            <source file='/tmp/image4.qcow'/>
            <backingStore type='file' index='5'>
              <format type='qcow2'/>
              <source file='/tmp/image5.qcow'/>
              <backingStore type='file' index='6'>
                <format type='raw'/>
                <source file='/tmp/Fedora-17-x86_64-Live-KDE.iso'/>
                <backingStore/>
              </backingStore>
            </backingStore>
          </backingStore>
        </backingStore>
      </backingStore>
    </backingStore>
    <target dev='vdb' bus='virtio'/>
  </disk>

Various disk types and formats can be mixed in one chain. The
<backingStore/> empty element marks the end of the backing chain and it
is there mostly for future support of parsing the chain provided by a
user. If it's missing, we are supposed to probe for the rest of the
chain ourselves, otherwise complete chain was provided by the user. The
index attributes of backingStore elements can be used to unambiguously
identify a specific part of the image chain.

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index e851f852a18234e8ac57ffa51ba31d4e20c018ed..93ee05c94eb9a3f6b98419497ea0fb7fe8cba983 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1624,6 +1624,20 @@
       </auth>
       <target dev='vda' bus='virtio'/>
     </disk>
+    <disk type='file' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source file='/var/lib/libvirt/images/domain.qcow'/>
+      <backingStore type='file'>
+        <format type='qcow2'/>
+        <source file='/var/lib/libvirt/images/snapshot.qcow'/>
+        <backingStore type='block'>
+          <format type='raw'/>
+          <source dev='/dev/mapper/base'/>
+          <backingStore/>
+        </backingStore>
+      </backingStore>
+      <target dev='vda' bus='virtio'/>
+    </disk>
   </devices>
   ...</pre>
 
@@ -1814,6 +1828,53 @@
         This feature doesn't support migration currently.
         </p>
         </dd>
+      <dt><code>backingStore</code></dt>
+      <dd>
+        This element describes the backing store used by the disk specified by
+        sibling <code>source</code> element. It is currently ignored on input
+        and only used for output to describe the detected backing chains.
+        <span class="since">Since 1.2.4</span>. An empty
+        <code>backingStore</code> element means the sibling source is
+        self-contained and is not based on any backing store. The following
+        attributes and sub-elements are supported in
+        <code>backingStore</code>:
+        <dl>
+          <dt><code>type</code> attribute</dt>
+          <dd>
+            The <code>type</code> attribute represents the type of disk used
+            by the backing store, see disk type attribute above for more
+            details and possible values.
+          </dd>
+          <dt><code>index</code> attribute</dt>
+          <dd>
+            This attribute is only valid in output (and ignored on input) and
+            it can be used to refer to a specific part of the disk chain when
+            doing block operations (such as via the
+            <code>virDomainBlockRebase</code> API). For example,
+            <code>vda[2]</code> refers to the backing store with
+            <code>index='2'</code> of the disk with <code>vda</code> target.
+          </dd>
+          <dt><code>format</code> sub-element</dt>
+          <dd>
+            The <code>format</code> element contains <code>type</code>
+            attribute which specifies the internal format of the backing
+            store, such as <code>raw</code> or <code>qcow2</code>.
+          </dd>
+          <dt><code>source</code> sub-element</dt>
+          <dd>
+            This element has the same structure as the <code>source</code>
+            element in <code>disk</code>. It specifies which file, device,
+            or network location contains the data of the described backing
+            store.
+          </dd>
+          <dt><code>backingStore</code> sub-element</dt>
+          <dd>
+            If the backing store is not self-contained, the next element
+            in the chain is described by nested <code>backingStore</code>
+            element.
+          </dd>
+        </dl>
+      </dd>
       <dt><code>mirror</code></dt>
       <dd>
         This element is present if the hypervisor has started a block

diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index d2235e1f566dc7ffffd96c0113b7ca2761db3b6a..4249ed56e66d54fa92cf09d37f1ed7b25f8de790 100644 (file)
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -1196,10 +1196,51 @@
       <optional>
         <ref name="snapshot"/>
       </optional>
-      <ref name="diskSource"/>
+      <interleave>
+        <ref name="diskSource"/>
+        <ref name="storageSourceExtra"/>
+        <ref name="diskBackingChain"/>
+      </interleave>
+    </element>
+  </define>
+
+  <define name="diskBackingChain">
+    <choice>
+      <ref name="diskBackingStore"/>
+      <ref name="diskBackingStoreLast"/>
+    </choice>
+  </define>
+
+  <define name="diskBackingStore">
+    <element name="backingStore">
+      <attribute name="index">
+        <ref name="positiveInteger"/>
+      </attribute>
+      <interleave>
+        <ref name="diskSource"/>
+        <ref name="diskBackingChain"/>
+        <ref name="diskFormat"/>
+      </interleave>
+    </element>
+  </define>
+
+  <define name="diskFormat">
+    <element name="format">
+      <attribute name="type">
+        <ref name="storageFormat"/>
+      </attribute>
+      <empty/>
     </element>
   </define>
 
+  <define name="diskBackingStoreLast">
+    <optional>
+      <element name="backingStore">
+        <empty/>
+      </element>
+    </optional>
+  </define>
+
   <define name="diskSource">
     <choice>
       <ref name="diskSourceFile"/>
@@ -1232,7 +1273,6 @@
           </optional>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1256,7 +1296,6 @@
           </optional>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1276,7 +1315,6 @@
           <empty/>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1340,7 +1378,6 @@
         </zeroOrMore>
         <empty/>
       </element>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 
@@ -1373,7 +1410,6 @@
           </optional>
         </element>
       </optional>
-      <ref name='storageSourceExtra'/>
     </interleave>
   </define>
 

diff --git a/tests/domainschemadata/backing-chains.xml b/tests/domainschemadata/backing-chains.xml
new file mode 100644 (file)
index 0000000..84df1db
--- /dev/null
+++ b/tests/domainschemadata/backing-chains.xml
@@ -0,0 +1,94 @@
+<domain type='qemu'>
+  <name>QEMUGuest1</name>
+  <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
+  <memory unit='KiB'>219136</memory>
+  <currentMemory unit='KiB'>219136</currentMemory>
+  <vcpu placement='static'>1</vcpu>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+    <boot dev='hd'/>
+  </os>
+  <clock offset='utc'/>
+  <on_poweroff>destroy</on_poweroff>
+  <on_reboot>restart</on_reboot>
+  <on_crash>destroy</on_crash>
+  <devices>
+    <emulator>/usr/bin/qemu</emulator>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source protocol='gluster' name='Volume2/Image'>
+        <host transport='unix' socket='/path/to/sock'/>
+      </source>
+      <backingStore type='file' index='1'>
+        <format type='qcow2'/>
+        <source file='/tmp/missing-backing-store.qcow'/>
+      </backingStore>
+      <target dev='vda' bus='virtio'/>
+    </disk>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source protocol='nbd' name='bar'>
+        <host transport='unix' socket='/var/run/nbdsock'/>
+      </source>
+      <backingStore type='block' index='1'>
+        <format type='qcow2'/>
+        <source dev='/dev/HostVG/QEMUGuest1'/>
+        <backingStore type='file' index='2'>
+          <format type='qcow2'/>
+          <source file='/tmp/image2.qcow'/>
+          <backingStore type='file' index='3'>
+            <format type='qcow2'/>
+            <source file='/tmp/image3.qcow'/>
+            <backingStore type='file' index='4'>
+              <format type='qcow2'/>
+              <source file='/tmp/image4.qcow'/>
+              <backingStore type='file' index='5'>
+                <source file='/tmp/image5.qcow'/>
+                <format type='qcow2'/>
+                <backingStore type='file' index='6'>
+                  <format type='raw'/>
+                  <source file='/tmp/Fedora-17-x86_64-Live-KDE.iso'/>
+                  <backingStore/>
+                </backingStore>
+              </backingStore>
+            </backingStore>
+          </backingStore>
+        </backingStore>
+      </backingStore>
+      <target dev='vdb' bus='virtio'/>
+    </disk>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='raw'/>
+      <backingStore/>
+      <source protocol='gluster' name='Volume1/Image'>
+        <host name='example.org' port='6000'/>
+      </source>
+      <target dev='vdc' bus='virtio'/>
+    </disk>
+    <disk type='network' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <auth username='myname'>
+        <secret type='ceph' usage='mycluster_myname'/>
+      </auth>
+      <source protocol='rbd' name='pool/image'>
+        <host name='mon1.example.org' port='6321'/>
+        <host name='mon2.example.org' port='6322'/>
+        <host name='mon3.example.org' port='6322'/>
+      </source>
+      <backingStore type='file' index='1'>
+        <source file='/tmp/image.qcow'/>
+        <backingStore/>
+        <format type='qcow2'/>
+      </backingStore>
+      <target dev='vdd' bus='virtio'/>
+    </disk>
+    <disk type='block' device='disk'>
+      <driver name='qemu' type='qcow2'/>
+      <source dev='/dev/HostVG/QEMUGuest11'/>
+      <target dev='vde' bus='virtio'/>
+    </disk>
+    <controller type='usb' index='0'/>
+    <controller type='pci' index='0' model='pci-root'/>
+    <memballoon model='virtio'/>
+  </devices>
+</domain>