[PATCH 25/32] docs: formatdomain-devices: Split out <rng>
Peter Krempa
pkrempa at redhat.com
Thu Jul 23 13:21:30 UTC 2020
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatdomain-devices-rng.rst | 76 ++++++++++++++++++++++++++++++
docs/formatdomain-devices.rst | 78 +------------------------------
docs/meson.build | 1 +
3 files changed, 78 insertions(+), 77 deletions(-)
create mode 100644 docs/formatdomain-devices-rng.rst
diff --git a/docs/formatdomain-devices-rng.rst b/docs/formatdomain-devices-rng.rst
new file mode 100644
index 0000000000..4e251d0959
--- /dev/null
+++ b/docs/formatdomain-devices-rng.rst
@@ -0,0 +1,76 @@
+:anchor:`<a id="elementsRng"/>`
+
+Random number generator device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The virtual random number generator device allows the host to pass through
+entropy to guest operating systems. :since:`Since 1.0.3`
+
+Example: usage of the RNG device:
+
+::
+
+ ...
+ <devices>
+ <rng model='virtio'>
+ <rate period="2000" bytes="1234"/>
+ <backend model='random'>/dev/random</backend>
+ <!-- OR -->
+ <backend model='egd' type='udp'>
+ <source mode='bind' service='1234'/>
+ <source mode='connect' host='1.2.3.4' service='1234'/>
+ </backend>
+ <!-- OR -->
+ <backend model='builtin'/>
+ </rng>
+ </devices>
+ ...
+
+``model``
+ The required ``model`` attribute specifies what type of RNG device is
+ provided. Valid values are specific to the virtualization platform:
+
+ - 'virtio' - supported by qemu and virtio-rng kernel module
+ - 'virtio-transitional' :since:`Since 5.2.0`
+ - 'virtio-non-transitional' :since:`Since 5.2.0`
+
+ See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
+ details.
+
+``rate``
+ The optional ``rate`` element allows limiting the rate at which entropy can
+ be consumed from the source. The mandatory attribute ``bytes`` specifies how
+ many bytes are permitted to be consumed per period. An optional ``period``
+ attribute specifies the duration of a period in milliseconds; if omitted, the
+ period is taken as 1000 milliseconds (1 second). :since:`Since 1.0.4`
+
+``backend``
+ The ``backend`` element specifies the source of entropy to be used for the
+ domain. The source model is configured using the ``model`` attribute.
+ Supported source models are:
+
+ ``random``
+ This backend type expects a non-blocking character device as input. The
+ file name is specified as contents of the ``backend`` element.
+ :since:`Since 1.3.4` any path is accepted. Before that ``/dev/random`` and
+ ``/dev/hwrng`` were the only accepted paths. When no file name is
+ specified, the hypervisor default is used. For QEMU, the default is
+ ``/dev/random``. However, the recommended source of entropy is
+ ``/dev/urandom`` (as it doesn't have the limitations of ``/dev/random``).
+
+ ``egd``
+ This backend connects to a source using the EGD protocol. The source is
+ specified as a character device. Refer to `character device host
+ interface <#elementsCharHostInterface>`__ for more information.
+
+ ``builtin``
+ This backend uses qemu builtin random generator, which uses
+ ``getrandom()`` syscall as the source of entropy. ( :since:`Since 6.1.0
+ and QEMU 4.2` )
+
+``driver``
+ The subelement ``driver`` can be used to tune the device:
+
+ virtio options
+ `Virtio-specific options <#elementsVirtio>`__ can also be set. (
+ :since:`Since 3.5.0` )
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index 35d1f0681a..1357a906b5 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -57,83 +57,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
.. include:: formatdomain-devices-sound.rst
.. include:: formatdomain-devices-watchdog.rst
.. include:: formatdomain-devices-memballoon.rst
-
-:anchor:`<a id="elementsRng"/>`
-
-Random number generator device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The virtual random number generator device allows the host to pass through
-entropy to guest operating systems. :since:`Since 1.0.3`
-
-Example: usage of the RNG device:
-
-::
-
- ...
- <devices>
- <rng model='virtio'>
- <rate period="2000" bytes="1234"/>
- <backend model='random'>/dev/random</backend>
- <!-- OR -->
- <backend model='egd' type='udp'>
- <source mode='bind' service='1234'/>
- <source mode='connect' host='1.2.3.4' service='1234'/>
- </backend>
- <!-- OR -->
- <backend model='builtin'/>
- </rng>
- </devices>
- ...
-
-``model``
- The required ``model`` attribute specifies what type of RNG device is
- provided. Valid values are specific to the virtualization platform:
-
- - 'virtio' - supported by qemu and virtio-rng kernel module
- - 'virtio-transitional' :since:`Since 5.2.0`
- - 'virtio-non-transitional' :since:`Since 5.2.0`
-
- See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
- details.
-
-``rate``
- The optional ``rate`` element allows limiting the rate at which entropy can
- be consumed from the source. The mandatory attribute ``bytes`` specifies how
- many bytes are permitted to be consumed per period. An optional ``period``
- attribute specifies the duration of a period in milliseconds; if omitted, the
- period is taken as 1000 milliseconds (1 second). :since:`Since 1.0.4`
-
-``backend``
- The ``backend`` element specifies the source of entropy to be used for the
- domain. The source model is configured using the ``model`` attribute.
- Supported source models are:
-
- ``random``
- This backend type expects a non-blocking character device as input. The
- file name is specified as contents of the ``backend`` element.
- :since:`Since 1.3.4` any path is accepted. Before that ``/dev/random`` and
- ``/dev/hwrng`` were the only accepted paths. When no file name is
- specified, the hypervisor default is used. For QEMU, the default is
- ``/dev/random``. However, the recommended source of entropy is
- ``/dev/urandom`` (as it doesn't have the limitations of ``/dev/random``).
-
- ``egd``
- This backend connects to a source using the EGD protocol. The source is
- specified as a character device. Refer to `character device host
- interface <#elementsCharHostInterface>`__ for more information.
-
- ``builtin``
- This backend uses qemu builtin random generator, which uses
- ``getrandom()`` syscall as the source of entropy. ( :since:`Since 6.1.0
- and QEMU 4.2` )
-
-``driver``
- The subelement ``driver`` can be used to tune the device:
-
- virtio options
- `Virtio-specific options <#elementsVirtio>`__ can also be set. (
- :since:`Since 3.5.0` )
+.. include:: formatdomain-devices-rng.rst
:anchor:`<a id="elementsTpm"/>`
diff --git a/docs/meson.build b/docs/meson.build
index 49f81cd687..43268be995 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -142,6 +142,7 @@ docs_rst_files = [
'formatdomain-devices-sound.rst',
'formatdomain-devices-watchdog.rst',
'formatdomain-devices-memballoon.rst',
+ 'formatdomain-devices-rng.rst',
]
},
{ 'name': 'hacking' },
--
2.26.2
More information about the libvir-list
mailing list