|
 |
c1c534 |
From 07ed5aa86d223b1e99ef716429be60c1823ce0f5 Mon Sep 17 00:00:00 2001
|
|
|
c1c534 |
Message-Id: <07ed5aa86d223b1e99ef716429be60c1823ce0f5@dist-git>
|
|
|
c1c534 |
From: Andrea Bolognani <abologna@redhat.com>
|
|
|
c1c534 |
Date: Wed, 29 Nov 2017 16:22:55 +0100
|
|
|
c1c534 |
Subject: [PATCH] docs: Improve documentation for serial consoles
|
|
|
c1c534 |
|
|
|
c1c534 |
Our current documentation is missing some information and doesn't
|
|
|
c1c534 |
do a great job at explaining how the <serial> and <console> elements
|
|
|
c1c534 |
are connected. Let's try to fix that.
|
|
|
c1c534 |
|
|
|
c1c534 |
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
|
|
|
c1c534 |
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
|
|
|
c1c534 |
(cherry picked from commit 4567cecb372c48095fce23ce3040d1c687cc3640)
|
|
|
c1c534 |
|
|
|
c1c534 |
https://bugzilla.redhat.com/show_bug.cgi?id=1449265
|
|
|
c1c534 |
https://bugzilla.redhat.com/show_bug.cgi?id=1511421
|
|
|
c1c534 |
https://bugzilla.redhat.com/show_bug.cgi?id=1512929
|
|
|
c1c534 |
https://bugzilla.redhat.com/show_bug.cgi?id=1512934
|
|
|
c1c534 |
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
|
|
|
c1c534 |
---
|
|
|
c1c534 |
docs/formatdomain.html.in | 224 +++++++++++++++++++++++++++++++++-------------
|
|
|
c1c534 |
1 file changed, 164 insertions(+), 60 deletions(-)
|
|
|
c1c534 |
|
|
|
c1c534 |
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
|
|
|
c1c534 |
index 4f28dce355..f57a124056 100644
|
|
|
c1c534 |
--- a/docs/formatdomain.html.in
|
|
|
c1c534 |
+++ b/docs/formatdomain.html.in
|
|
|
c1c534 |
@@ -6434,77 +6434,68 @@ qemu-kvm -net nic,model=? /dev/null
|
|
|
c1c534 |
|
|
|
c1c534 |
...
|
|
|
c1c534 |
<devices>
|
|
|
c1c534 |
+ <!-- Serial port -->
|
|
|
c1c534 |
<serial type='pty'>
|
|
|
c1c534 |
<source path='/dev/pts/3'/>
|
|
|
c1c534 |
<target port='0'/>
|
|
|
c1c534 |
</serial>
|
|
|
c1c534 |
</devices>
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+<devices>
|
|
|
c1c534 |
+ <!-- USB serial port -->
|
|
|
c1c534 |
+ <serial type='pty'>
|
|
|
c1c534 |
+ <target type='usb-serial' port='0'/>
|
|
|
c1c534 |
+ <address type='usb' bus='0' port='1'/>
|
|
|
c1c534 |
+ </serial>
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
...
|
|
|
c1c534 |
|
|
|
c1c534 |
|
|
|
c1c534 |
- target can have a port attribute, which
|
|
|
c1c534 |
- specifies the port number. Ports are numbered starting from 0. There are
|
|
|
c1c534 |
- usually 0, 1 or 2 serial ports. There is also an optional
|
|
|
c1c534 |
- type attribute since 1.0.2
|
|
|
c1c534 |
- which has three choices for its value, one is isa-serial,
|
|
|
c1c534 |
- then usb-serial and last one is pci-serial.
|
|
|
c1c534 |
- If type is missing, isa-serial will be used by
|
|
|
c1c534 |
- default. For usb-serial an optional sub-element
|
|
|
c1c534 |
- <address/> with type='usb' can tie the
|
|
|
c1c534 |
- device to a particular controller, documented above.
|
|
|
c1c534 |
- Similarly, pci-serial can be used to attach the device to
|
|
|
c1c534 |
- the pci bus (since 1.2.16). Again, it has
|
|
|
c1c534 |
- optional sub-element <address/> with
|
|
|
c1c534 |
- type='pci' to select desired location on the PCI bus.
|
|
|
c1c534 |
+ The target element can have an optional port
|
|
|
c1c534 |
+ attribute, which specifies the port number (starting from 0), and an
|
|
|
c1c534 |
+ optional type attribute: valid values are,
|
|
|
c1c534 |
+ since 1.0.2, isa-serial (usable
|
|
|
c1c534 |
+ with x86 guests), usb-serial (usable whenever USB support
|
|
|
c1c534 |
+ is available) and pci-serial (usable whenever PCI support
|
|
|
c1c534 |
+ is available).
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ If any of the attributes is not specified by the user, libvirt will
|
|
|
c1c534 |
+ choose a value suitable for most users.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ All of the target types support configuring the guest-visible device
|
|
|
c1c534 |
+ address as documented above; more
|
|
|
c1c534 |
+ specifically, acceptable address types are isa (for
|
|
|
c1c534 |
+ isa-serial), usb (for usb-serial)
|
|
|
c1c534 |
+ and pci (for pci-serial).
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ For the relationship between serial ports and consoles,
|
|
|
c1c534 |
+ see below.
|
|
|
c1c534 |
|
|
|
c1c534 |
|
|
|
c1c534 |
|
|
|
c1c534 |
|
|
|
c1c534 |
-
|
|
|
c1c534 |
- The console element is used to represent interactive consoles. Depending
|
|
|
c1c534 |
- on the type of guest in use, the consoles might be paravirtualized devices,
|
|
|
c1c534 |
- or they might be a clone of a serial device, according to the following
|
|
|
c1c534 |
- rules:
|
|
|
c1c534 |
-
|
|
|
c1c534 |
-
|
|
|
c1c534 |
-
|
|
|
c1c534 |
- If no targetType attribute is set, then the default
|
|
|
c1c534 |
- device type is according to the hypervisor's rules. The default
|
|
|
c1c534 |
- type will be added when re-querying the XML fed into libvirt.
|
|
|
c1c534 |
- For fully virtualized guests, the default device type will usually
|
|
|
c1c534 |
- be a serial port.
|
|
|
c1c534 |
- If the targetType attribute is serial,
|
|
|
c1c534 |
- then if no <serial> element exists, the console
|
|
|
c1c534 |
- element will be copied to the serial element. If a <serial>
|
|
|
c1c534 |
- element does already exist, the console element will be ignored.
|
|
|
c1c534 |
- If the targetType attribute is not serial,
|
|
|
c1c534 |
- it will be treated normally.
|
|
|
c1c534 |
- Only the first console element may use a targetType
|
|
|
c1c534 |
- of serial. Secondary consoles must all be paravirtualized.
|
|
|
c1c534 |
-
|
|
|
c1c534 |
- On S390, the console element may use a
|
|
|
c1c534 |
- targetType of sclp or sclplm
|
|
|
c1c534 |
- (line mode). SCLP is the native console type for S390. There's no
|
|
|
c1c534 |
- controller associated to SCLP consoles.
|
|
|
c1c534 |
- Since 1.0.2
|
|
|
c1c534 |
-
|
|
|
c1c534 |
-
|
|
|
c1c534 |
-
|
|
|
c1c534 |
-
|
|
|
c1c534 |
- A virtio console device is exposed in the
|
|
|
c1c534 |
- guest as /dev/hvc[0-7] (for more information, see
|
|
|
c1c534 |
- http://fedoraproject.org/wiki/Features/VirtioSerial)
|
|
|
c1c534 |
- Since 0.8.3
|
|
|
c1c534 |
-
|
|
|
c1c534 |
-
|
|
|
c1c534 |
|
|
|
c1c534 |
...
|
|
|
c1c534 |
<devices>
|
|
|
c1c534 |
+ <!-- Serial console -->
|
|
|
c1c534 |
<console type='pty'>
|
|
|
c1c534 |
- <source path='/dev/pts/4'/>
|
|
|
c1c534 |
- <target port='0'/>
|
|
|
c1c534 |
+ <source path='/dev/pts/2'/>
|
|
|
c1c534 |
+ <target type='serial' port='0'/>
|
|
|
c1c534 |
</console>
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
<!-- KVM virtio console -->
|
|
|
c1c534 |
<console type='pty'>
|
|
|
c1c534 |
<source path='/dev/pts/5'/>
|
|
|
c1c534 |
@@ -6513,21 +6504,134 @@ qemu-kvm -net nic,model=? /dev/null
|
|
|
c1c534 |
</devices>
|
|
|
c1c534 |
...
|
|
|
c1c534 |
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ The console element is used to represent interactive
|
|
|
c1c534 |
+ serial consoles. Depending on the type of guest in use and the specifics
|
|
|
c1c534 |
+ of the configuration, the console element might represent
|
|
|
c1c534 |
+ the same device as an existing serial element or a separate
|
|
|
c1c534 |
+ device.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ A target subelement is supported and works the same
|
|
|
c1c534 |
+ way as with the serial element
|
|
|
c1c534 |
+ (see above for details).
|
|
|
c1c534 |
+ Valid values for the type attribute are:
|
|
|
c1c534 |
+ serial (described below);
|
|
|
c1c534 |
+ virtio (usable whenever VirtIO support is available);
|
|
|
c1c534 |
+ xen, lxc, uml and
|
|
|
c1c534 |
+ openvz (available when the corresponding hypervisor is in
|
|
|
c1c534 |
+ use); sclp and sclplm (usable for s390 and
|
|
|
c1c534 |
+ s390x QEMU guests).
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ Of the target types listed above, serial is special in
|
|
|
c1c534 |
+ that it doesn't represents a separate device, but rather the same
|
|
|
c1c534 |
+ device as the first serial element. Due to this, there can
|
|
|
c1c534 |
+ only be a single console element with target type
|
|
|
c1c534 |
+ serial per guest.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ Virtio consoles are usually accessible as /dev/hvc[0-7]
|
|
|
c1c534 |
+ from inside the guest; for more information, see
|
|
|
c1c534 |
+ http://fedoraproject.org/wiki/Features/VirtioSerial.
|
|
|
c1c534 |
+ Since 0.8.3
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ For the relationship between serial ports and consoles,
|
|
|
c1c534 |
+ see below.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ Due to hystorical reasons, the serial and
|
|
|
c1c534 |
+ console elements have partially overlapping scopes.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ In general, both elements are used to configure one or more serial
|
|
|
c1c534 |
+ consoles to be used for interacting with the guest. The main difference
|
|
|
c1c534 |
+ between the two is that serial is used for emulated,
|
|
|
c1c534 |
+ usually native, serial consoles, whereas console is used
|
|
|
c1c534 |
+ for paravirtualized ones.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ Both emulated and paravirtualized serial consoles have advantages and
|
|
|
c1c534 |
+ disadvantages:
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ emulated serial consoles are usually initialized much earlier than
|
|
|
c1c534 |
+ paravirtualized ones, so they can be used to control the bootloader
|
|
|
c1c534 |
+ and display both firmware and early boot messages;
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ on several platforms, there can only be a single emulated serial
|
|
|
c1c534 |
+ console per guest but paravirtualized consoles don't suffer from the
|
|
|
c1c534 |
+ same limitation.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ A configuration such as:
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
|
|
|
c1c534 |
...
|
|
|
c1c534 |
-<devices>
|
|
|
c1c534 |
- <!-- KVM S390 sclp console -->
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
<console type='pty'>
|
|
|
c1c534 |
- <source path='/dev/pts/1'/>
|
|
|
c1c534 |
- <target type='sclp' port='0'/>
|
|
|
c1c534 |
+ <target type='serial'/>
|
|
|
c1c534 |
+ </console>
|
|
|
c1c534 |
+ <console type='pty'>
|
|
|
c1c534 |
+ <target type='virtio'/>
|
|
|
c1c534 |
</console>
|
|
|
c1c534 |
</devices>
|
|
|
c1c534 |
...
|
|
|
c1c534 |
|
|
|
c1c534 |
|
|
|
c1c534 |
- If the console is presented as a serial port, the target
|
|
|
c1c534 |
- element has the same attributes as for a serial port. There is usually
|
|
|
c1c534 |
- only 1 console.
|
|
|
c1c534 |
+ will work on any platform and will result in one emulated serial console
|
|
|
c1c534 |
+ for early boot logging / interactive / recovery use, and one
|
|
|
c1c534 |
+ paravirtualized serial console to be used eg. as a side channel. Most
|
|
|
c1c534 |
+ people will be fine with having just the first console
|
|
|
c1c534 |
+ element in their configuration.
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ Note that, due to the compatibility concerns mentioned earlier, all the
|
|
|
c1c534 |
+ following configurations:
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
+ <serial type='pty'/>
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
+ <console type='pty'/>
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
+ <serial type='pty'/>
|
|
|
c1c534 |
+ <console type='pty'/>
|
|
|
c1c534 |
+</devices>
|
|
|
c1c534 |
+...
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+
|
|
|
c1c534 |
+ will be treated the same and will result in a single emulated serial
|
|
|
c1c534 |
+ console being available to the guest.
|
|
|
c1c534 |
|
|
|
c1c534 |
|
|
|
c1c534 |
|
|
|
c1c534 |
--
|
|
|
c1c534 |
2.15.1
|
|
|
c1c534 |
|