Document possible hypervisor bug in serial_console

This is described in Issue 83.

Update both the install guide and the gnt-instance manpage.
In the install guide move another KVM specific example inside a new KVM
admonition for the hypervisor parameters section.

Signed-off-by: Guido Trotter <ultrotter@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

diff --git a/doc/install.rst b/doc/install.rst
index ec1c6ab..8f753d6 100644 (file)
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -721,10 +721,19 @@ modify``.
 Your instance types, networking environment, hypervisor type and version
 may all affect what kind of parameters should be used on your cluster.
 
-For example kvm instances are by default configured to use a host
-kernel, and to be reached via serial console, which works nice for Linux
-paravirtualized instances. If you want fully virtualized instances you
-may want to handle their kernel inside the instance, and to use VNC.
+.. admonition:: KVM
+
+  Instances are by default configured to use a host kernel, and to be
+  reached via serial console, which works nice for Linux paravirtualized
+  instances. If you want fully virtualized instances you may want to
+  handle their kernel inside the instance, and to use VNC.
+
+  Some versions of KVM have a bug that will make an instance hang when
+  configured to use the serial console (which is the default) unless a
+  connection is made to it within about 2 seconds of the instance's
+  startup. For such case it's recommended to disable the
+  ``serial_console`` option.
+
 
 Joining the nodes to the cluster
 ++++++++++++++++++++++++++++++++

diff --git a/man/gnt-instance.rst b/man/gnt-instance.rst
index 6fe996b..d5c7d09 100644 (file)
--- a/man/gnt-instance.rst
+++ b/man/gnt-instance.rst
@@ -492,7 +492,11 @@ serial\_console
     Valid for the KVM hypervisor.
 
     This boolean option specifies whether to emulate a serial console
-    for the instance.
+    for the instance. Note that some versions of KVM have a bug that
+    will make an instance hang when configured to use the serial console
+    unless a connection is made to it within about 2 seconds of the
+    instance's startup. For such case it's recommended to disable this
+    option, which is enabled by default.
 
 serial\_speed
     Valid for the KVM hypervisor.