[pve-devel] [PATCH docs 5/5] Add documentation for virtio-rng

[Aaron Lauterer]

Looks good. I have a few comments inline, some surplus commas that are 
not needed and some slight rephrasing.

On 2/20/20 6:10 PM, Stefan Reiter wrote:
> Signed-off-by: Stefan Reiter <s.reiter at proxmox.com>
> ---
>   qm.adoc | 38 ++++++++++++++++++++++++++++++++++++++
>   1 file changed, 38 insertions(+)
> 
> diff --git a/qm.adoc b/qm.adoc
> index 0b699e2..3e6d135 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -791,6 +791,44 @@ device of the host use device passthrough (see
>   xref:qm_pci_passthrough[PCI Passthrough] and
>   xref:qm_usb_passthrough[USB Passthrough]).
>   
> +[[qm_virtio_rng]]
> +VirtIO RNG
> +~~~~~~~~~~
> +
> +A RNG (Random Number Generator) is a device providing entropy ('randomness')
> +to a system. A virtual hardware-RNG can be used to provide such entropy from the
> +host system to a guest VM. This helps avoid entropy starvation problems in the
s/helps avoid/helps to avoid/

> +guest (a situation where not enough entropy is available, and the system may
s/available, and/available and/

> +slow down or run into problems), especially during guest bootup.
s/during guest/during the guests/
or
s/during guest bootup/during the boot process of the guest/

> +
> +To add a VirtIO-based emulated RNG, run the following command:
> +
> +----
> +qm set <vmid> -rng0 source=<source>[,max_bytes=X,period=Y]
> +----
> +
> +`source` specifies where entropy is read from on the host, and has to be one of
s/host, and/host and/

> +the following:
> +
> +* `/dev/urandom`: Non-blocking kernel entropy pool (preferred)
> +* `/dev/random`: Blocking kernel pool (not recommended, can lead to entropy
> +  starvation on the host system)
> +* `/dev/hwrng`: To pass through a hardware RNG attached to the host (if multiple
> +  are available, the one selected in
> +  `/sys/devices/virtual/misc/hw_random/rng_current` will be used)
> +
> +A limit can be specified via the `max_bytes` and `period` parameters, they are
> +read as `max_bytes` per `period` in milliseconds. However, it does not represent
> +a linear relationship: 1024B/1000ms would mean that up to 1 KiB of data become
s/data become/data {will,would} become/

> +available on a 1 second timer, not that 1 KiB is streamed to the guest over the
> +course of one second. Reducing the `period` can thus be used to inject entropy
> +into the guest at a faster rate.
> +
> +By default, the limit is set to 1024 bytes per 1000 ms (1 KiB/s). It is
> +recommended to always use a limiter, to avoid guests using too many host
s/limiter, to/limiter to/

> +resources, but if desired, a value of '0' for `max_bytes` can be used to disable
s/resources, but if/resourced. If/

> +all limiting.
s/limiting/limitations/

> +
>   [[qm_startup_and_shutdown]]
>   Automatic Start and Shutdown of Virtual Machines
>   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>