From: Peter Krempa <pkrempa@redhat.com>
Date: Thu, 20 Dec 2012 11:06:52 +0000 (+0100)
Subject: doc: schema: Add basic documentation for the virtual RNG device support
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=fa16c80f52136371dcc88649052fd9f7adff73eb;p=libvirt.git

doc: schema: Add basic documentation for the virtual RNG device support

This patch documents XML elements used for (basic) support of virtual
RNG devices.

In the devices section in the domain XML users may specify:

For the default 'random' backend:
  <devices>
    <rng model='virtio'>
      <backend model='random'>/dev/urandom</backend>
    </rng>
  </devices>

For the slightly more advanced EGD backend:
  <devices>
    <rng model='virtio'>
      <backend model='egd' type='udp'>
        <!-- this is a definition of a character device -->
        <source mode='bind' service='1234'/>
        <source mode='connect' host='1.2.3.4' service='1234'/>
        <!-- or other valid character device configuration -->
      </backend>
    </rng>
  </devices>

For the planned random daemon/pool:
  <devices>
    <rng model='virtio'>
      <backend model='pool' pool='poolname'>class</backend>
    </rng>
  </devices>

to enable the RNG device for guests.
---

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index a9003d70d6..12c946858a 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -4279,6 +4279,75 @@ qemu-kvm -net nic,model=? /dev/null
         </ul>
       </dd>
     </dl>
+    <h4><a name="elementsRng">Random number generator device</a></h4>
+
+    <p>
+      The virtual random number generator device allows the host to pass
+      through entropy to guest operating systems.
+      <span class="since">Since 1.0.3</span>
+    </p>
+
+    <p>
+      Example: usage of the RNG device:
+    </p>
+<pre>
+  ...
+  &lt;devices&gt;
+    &lt;rng model='virtio'&gt;
+      &lt;backend model='random'&gt;/dev/random&lt;/backend&gt;
+      &lt;!-- OR --&gt;
+      &lt;backend model='egd' type='udp'&gt;
+        &lt;source mode='bind' service='1234'&gt;
+        &lt;source mode='connect' host='1.2.3.4' service='1234'&gt;
+      &lt;/backend&gt;
+    &lt;/rng&gt;
+  &lt;/devices&gt;
+  ...
+</pre>
+    <dl>
+      <dt><code>model</code></dt>
+      <dd>
+        <p>
+          The required <code>model</code> attribute specifies what type
+          of RNG device is provided. Valid values are specific to
+          the virtualization platform:
+        </p>
+        <ul>
+          <li>'virtio' &mdash; supported by qemu and virtio-rng kernel module</li>
+        </ul>
+      </dd>
+      <dt><code>backend</code></dt>
+      <dd>
+        <p>
+          The <code>backend</code> element specifies the source of entropy
+          to be used for the domain. The source model is configured using the
+          <code>model</code> attribute. Supported source models are:
+        </p>
+        <ul>
+          <li>'random' &mdash; /dev/random (default) or similar device as source</li>
+          <li>'egd' &mdash; a EGD protocol backend</li>
+        </ul>
+      </dd>
+      <dt><code>backend type='random'</code></dt>
+      <dd>
+        <p>
+          This backend type expects a non-blocking character device as input.
+          Examples of such devices are /dev/random and /dev/urandom. The file
+          name is specified as contents of the <code>backend</code> element.
+          When no file name is specified the hypervisor default is used.
+        </p>
+      </dd>
+      <dt><code>backend type='egd'</code></dt>
+      <dd>
+        <p>
+          This backend connects to a source using the EGD protocol.
+          The source is specified as a character device. Refer to
+          <a href='#elementsCharHostInterface'>character device host interface</a>
+          for more information.
+        </p>
+      </dd>
+
+    </dl>
 
     <h3><a name="seclabel">Security label</a></h3>
 
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index 63be4aaebc..8330a507ff 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -3126,6 +3126,7 @@
             <ref name="hub"/>
             <ref name="redirdev"/>
             <ref name="redirfilter"/>
+            <ref name="rng"/>
           </choice>
         </zeroOrMore>
         <optional>
@@ -3514,6 +3515,37 @@
     </element>
   </define>
 
+  <define name="rng">
+    <element name="rng">
+      <attribute name="model">
+        <choice>
+          <value>virtio</value>
+        </choice>
+      </attribute>
+      <ref name="rng-backend"/>
+    </element>
+  </define>
+
+  <define name="rng-backend">
+    <element name="backend">
+      <choice>
+        <group>
+          <attribute name="model">
+            <value>random</value>
+          </attribute>
+          <ref name="filePath"/>
+        </group>
+        <group>
+          <attribute name="model">
+            <value>egd</value>
+          </attribute>
+          <ref name="qemucdevSrcType"/>
+          <ref name="qemucdevSrcDef"/>
+        </group>
+      </choice>
+    </element>
+  </define>
+
   <define name="usbmaster">
     <element name="master">
       <attribute name="startport">