[PATCH 25/32] docs: formatdomain-devices: Split out <rng>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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