[libvirt] [PATCH 1/4] doc: schema: Add basic documentation for the virtual RNG device support

Eric Blake eblake at redhat.com
Mon Jan 28 22:27:48 UTC 2013


On 01/11/2013 10:00 AM, Peter Krempa wrote:
> This patch documments XML elements used for (basic) support of virtual

s/documments/documents/

> RNG devices.
> 
> In the devices section in the domain XML users may specify:
> 
>   <devices>
>     <rng model='none'/>

Do we need model='none'?  Historically, we have added it for devices
where the device used to be always-on by default, but we didn't have XML
for the device, then later on the device became optional so we had to
have a way to express the absence of the device without breaking
back-compat of old XML that gets the default for free.  But in the case
of rng, I don't think we currently have any device for free, so
model='none' doesn't seem to add anything.

>   </devices>
> 
> and the more useful variant:
> 
>   <devices>
>     <rng model='virtio'>
>       <source type='random'>/dev/urandom</source>
>     </rng>
>   </devices>

This part, however, seems reasonable.

> ---
>  docs/formatdomain.html.in     | 54 +++++++++++++++++++++++++++++++++++++++++++
>  docs/schemas/domaincommon.rng | 31 +++++++++++++++++++++++++
>  2 files changed, 85 insertions(+)
> 
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index bb0b199..7a5f267 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -4260,6 +4260,60 @@ 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.2</span>

Yikes - our delay in reviewing this means that it might not make 1.0.2
after all.  It's probably a good sign that the list is now getting so
many patches, but at the same time it points out that everyone needs to
help more with reviews.

> +      <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>'none' — disable the rng device</li>

Again, isn't omitting the <rng> element sufficient for this task?

> +          <li>'virtio' — supported by qemu and virtio-rng kernel module</li>
> +        </ul>
> +      </dd>
> +      <dt><code>source</code></dt>
> +      <dd>
> +        <p>
> +          The <code>source</code> element specifies the source of entropy
> +          to be used for the doimain. The source type is configured using the

s/doimain/domain/

> +          <code>type</code> attribute. Supported source types are:
> +        </p>
> +        <ul>
> +          <li>'none' — no source was configured</li>
> +          <li>'random' — /dev/random or similar device as source</li>

Here, it _does_ make sense to expose both a type='none' and
type='random'; assuming that qemu has a default source of entropy that
it uses when libvirt doesn't specify one.

> +        </ul>
> +      </dd>
> +      <dt><code>source type='random'</code></dt>
> +      <dd>
> +        <p>
> +          This source 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>source</code> element.

Side question - is it also possible to pass a (large) regular file, so
that you can experiment with reproducible random replays?  At least with
coreutil's 'shuf --random-source', it is indeed possible to replay a
particular byte stream (obviously, on reply, the element of true
randomness is gone, but for analysis purposes, it can still be a useful
thing to do).

I guess what this means for libvirt is that we should allow whatever
file name the user passes, rather than actually stat()ing the file and
enforcing that it be a char device.

> 
> +  <define name="rng">
> +    <element name="rng">
> +      <attribute name="model">
> +        <choice>
> +          <value>none</value>
> +          <value>virtio</value>
> +        </choice>

Again, not sure we need this level of <choice>.

> +      </attribute>
> +    </element>
> +  </define>
> +
> +  <define name="rng-source">
> +    <element name="source">
> +      <choice>
> +        <group>
> +          <attribute name="type">
> +            <value>none</value>
> +          </attribute>
> +          <empty/>
> +        </group>
> +        <group>
> +          <attribute name="type">
> +            <value>random</value>
> +          </attribute>
> +          <ref name="filePath"/>
> +        </group>
> +      </choice>
> +    </element>
> +  </define>

This part looks fine.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 621 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130128/3f7d5cf4/attachment-0001.sig>


More information about the libvir-list mailing list