[libvirt PATCH] docs: Improve documentation for <serial> and <console>

Andrea Bolognani abologna at redhat.com
Tue Feb 11 14:44:40 UTC 2020


Users expect to be able to configure the <console> element and see
that configuration reflected into the <serial> element or at least
sticking, however due to our crazy back-compat code that doesn't
always happen.

There's really not much we can do to make this kind of corner cases
work as the user would expect, especially not without introducing
additional complexity in a part of libvirt that already has more
than a fair share of it; we can, however, improve the documentation
so that it will nudge said users in the right direction.

https://bugzilla.redhat.com/show_bug.cgi?id=1770725

Signed-off-by: Andrea Bolognani <abologna at redhat.com>
---
 docs/formatdomain.html.in | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 44e2062d01..5ccf39abd1 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -7510,7 +7510,10 @@ qemu-kvm -net nic,model=? /dev/null
       <span class="since">since 4.7.0</span>, <code>16550a</code> (usable
       with the <code>system-serial</code> target type);
       <code>sclpconsole</code> and <code>sclplmconsole</code> (usable with
-      the <code>sclp-serial</code> target type).
+      the <code>sclp-serial</code> target type). Providing a target model is
+      usually unnecessary: libvirt will automatically pick one that's suitable
+      for the chosen target type, and overriding that value is generally not
+      recommended.
     </p>
 
     <p>
@@ -7656,7 +7659,8 @@ qemu-kvm -net nic,model=? /dev/null
       for early boot logging / interactive / recovery use, and one
       paravirtualized serial console to be used eg. as a side channel. Most
       people will be fine with having just the first <code>console</code>
-      element in their configuration.
+      element in their configuration, but if a specific configuration is
+      desired then both elements should be specified.
     </p>
 
     <p>
-- 
2.24.1




More information about the libvir-list mailing list