[libvirt] [PATCHv2 2/8] doc: schema: Add basic documentation for the virtual RNG device support

[Peter Krempa]

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>
  </devices>

to enable the RNG device for guests.
---

Notes:
    Version 2:
    - ACKed, no change, unfortunately doesn't make sense to push alone

 docs/formatdomain.html.in     | 69 +++++++++++++++++++++++++++++++++++++++++++
 docs/schemas/domaincommon.rng | 32 ++++++++++++++++++++
 2 files changed, 101 insertions(+)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index ffcc33e..e8cd086 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -4278,6 +4278,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 doimain. 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 63be4aa..8330a50 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">
-- 
1.8.1.1

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list