Add page describing use of ChaosKey with virtual machines

Signed-off-by: Keith Packard <keithp@keithp.com>

6 files changed, 76 insertions, 0 deletions

diff --git a/ChaosKey/VirtualMachine.mdwn b/ChaosKey/VirtualMachine.mdwn
new file mode 100644
index 0000000..7aa5848
--- /dev/null
+++ b/ChaosKey/VirtualMachine.mdwn
@@ -0,0 +1,70 @@
+# ChaosKey and Virtual Machines
+
+Using ChaosKey in a bare metal environment is really easy; you just
+plug it in and your kernel entropy pool is chock full and ready to go.
+
+Sharing random data with guests running on the same machine is pretty
+straight forward as well as kvm and qemu have a pass-through device,
+virtio-rng, which can pull data from the host entropy pool and use
+that in the guest.
+
+## Adding an rng device to the virtual machine
+
+First, you'll need to configure qemu to provide a virtual device
+inside the guest.
+
+### Adding an rng device with virt-manager
+
+Virt-manager provides a graphical interface to managing virtual
+machines.
+
+[[!img images/virt-manager.png]]
+
+Select the host you want to add the virtio-rng device to, open it up
+and click on the lightbulb (Show virtual hardware details) button:
+
+[[!img images/machine-overview.png]]
+
+Click on the +Add Hardware button to open up the Add New Virtual
+Hardware dialog:
+
+[[!img images/add-hardware.png]]
+
+Select RNG to show the Random Number Generator view:
+
+[[!img images/add-rng.png]]
+
+Click on Finish and you're all done.
+
+### Adding an rng device with virsh edit
+
+As root:
+
+	# virsh edit <name>
+
+Add the virtio-rng device inside the <devices></devices> element:
+
+	<devices>
+	  ...
+	  <rng model='virtio'>
+	    <backend model='random'>/dev/random</backend>
+	    <address type='pci' domain='0x0000' bus='0x00' slot='0x09' function='0x0'/>
+	  </rng>
+	</devices>
+
+## Adding virtio-rng to the guest OS
+
+If you're using a distribution kernel in the guest, it should already
+have the virtio-rng device built and available. Once you have the
+device available in the virtual machine, boot the guest and 
+check to make sure the virtio_rng module has been loaded.
+
+For guests running kernel version 3.17 or later, that's all you need
+to do -- the kernel will automatically create a thread to read data as
+needed from the host's random pool.
+
+For guests running kernel version 3.16 or older, the kernel doesn't
+create a thread to read data from the host, so you need to run the
+rngd daemon. On Debian, that's a simple matter of installing the
+rng-tools package. Other distributions presumably have a package that
+does something similar.
diff --git a/ChaosKey/images/add-hardware.png b/ChaosKey/images/add-hardware.png
new file mode 100644
index 0000000..79a0cf5
--- /dev/null
+++ b/ChaosKey/images/add-hardware.png
diff --git a/ChaosKey/images/add-rng.png b/ChaosKey/images/add-rng.png
new file mode 100644
index 0000000..8089f6c
--- /dev/null
+++ b/ChaosKey/images/add-rng.png
diff --git a/ChaosKey/images/machine-overview.png b/ChaosKey/images/machine-overview.png
new file mode 100644
index 0000000..fda122f
--- /dev/null
+++ b/ChaosKey/images/machine-overview.png
diff --git a/ChaosKey/images/virt-manager.png b/ChaosKey/images/virt-manager.png
new file mode 100644
index 0000000..742b377
--- /dev/null
+++ b/ChaosKey/images/virt-manager.png
diff --git a/ChaosKey/index.mdwn b/ChaosKey/index.mdwn
index 4da6c8f..19840ba 100644
--- a/ChaosKey/index.mdwn
+++ b/ChaosKey/index.mdwn
@@ -2,6 +2,12 @@
 
 This is a hardware True Random Number Generator that attaches via USB.
 
+The Linux Kernel, starting with version 4.1, includes source for this
+driver. It should be built by default in your distribution. If your
+using Linux + KVM to host other Linux instances, read the
+VirtualMachine page to see how you can configure the guests to share
+the host entropy source.
+
 ## Version 1.0 ##
 
 1.0 is the first production version of ChaosKey. The first run of 1000