[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [PATCHv2 2/8] 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>
  </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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]