[PATCH 21/32] docs: formatdomain-devices: Split out chardevs

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-chardev.rst | 682 +++++++++++++++++++++++++ docs/formatdomain-devices.rst | 684 +------------------------- docs/meson.build | 1 + 3 files changed, 684 insertions(+), 683 deletions(-) create mode 100644 docs/formatdomain-devices-chardev.rst diff --git a/docs/formatdomain-devices-chardev.rst b/docs/formatdomain-devices-chardev.rst new file mode 100644 index 0000000000..120b045b8f --- /dev/null +++ b/docs/formatdomain-devices-chardev.rst @@ -0,0 +1,682 @@ +:anchor:`<a id="elementsConsole"/>` + +Consoles, serial, parallel & channel devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A character device provides a way to interact with the virtual machine. +Paravirtualized consoles, serial ports, parallel ports and channels are all +classed as character devices and so represented using the same syntax. + +:: + + ... + <devices> + <parallel type='pty'> + <source path='/dev/pts/2'/> + <target port='0'/> + </parallel> + <serial type='pty'> + <source path='/dev/pts/3'/> + <target port='0'/> + </serial> + <serial type='file'> + <source path='/tmp/file' append='on'> + <seclabel model='dac' relabel='no'/> + </source> + <target port='0'/> + </serial> + <console type='pty'> + <source path='/dev/pts/4'/> + <target port='0'/> + </console> + <channel type='unix'> + <source mode='bind' path='/tmp/guestfwd'/> + <target type='guestfwd' address='10.0.2.1' port='4600'/> + </channel> + </devices> + ... + +In each of these directives, the top-level element name (parallel, serial, +console, channel) describes how the device is presented to the guest. The guest +interface is configured by the ``target`` element. + +The interface presented to the host is given in the ``type`` attribute of the +top-level element. The host interface is configured by the ``source`` element. + +The ``source`` element may contain an optional ``seclabel`` to override the way +that labelling is done on the socket path. If this element is not present, the +`security label is inherited from the per-domain setting <#seclabel>`__. + +If the interface ``type`` presented to the host is "file", then the ``source`` +element may contain an optional attribute ``append`` that specifies whether or +not the information in the file should be preserved on domain restart. Allowed +values are "on" and "off" (default). :since:`Since 1.3.1` . + +Regardless of the ``type``, character devices can have an optional log file +associated with them. This is expressed via a ``log`` sub-element, with a +``file`` attribute. There can also be an ``append`` attribute which takes the +same values described above. :since:`Since 1.3.3` . + +:: + + ... + <log file="/var/log/libvirt/qemu/guestname-serial0.log" append="off"/> + ... + +Each character device element has an optional sub-element ``<address>`` which +can tie the device to a particular `controller <#elementsControllers>`__ or PCI +slot. + +For character device with type ``unix`` or ``tcp`` the ``source`` has an +optional element ``reconnect`` which configures reconnect timeout if the +connection is lost. There are two attributes, ``enabled`` where possible values +are "yes" and "no" and ``timeout`` which is in seconds. The ``reconnect`` +attribute is valid only for ``connect`` mode. :since:`Since 3.7.0 (QEMU driver +only)` . + +:anchor:`<a id="elementsCharGuestInterface"/>` + +Guest interface +^^^^^^^^^^^^^^^ + +A character device presents itself to the guest as one of the following types. + +:anchor:`<a id="elementCharParallel"/>` + +Parallel port +''''''''''''' + +:: + + ... + <devices> + <parallel type='pty'> + <source path='/dev/pts/2'/> + <target port='0'/> + </parallel> + </devices> + ... + +``target`` can have a ``port`` attribute, which specifies the port number. Ports +are numbered starting from 0. There are usually 0, 1 or 2 parallel ports. + +:anchor:`<a id="elementCharSerial"/>` + +Serial port +''''''''''' + +:: + + ... + <devices> + <!-- Serial port --> + <serial type='pty'> + <source path='/dev/pts/3'/> + <target port='0'/> + </serial> + </devices> + ... + +:: + + ... + <devices> + <!-- USB serial port --> + <serial type='pty'> + <target type='usb-serial' port='0'> + <model name='usb-serial'/> + </target> + <address type='usb' bus='0' port='1'/> + </serial> + </devices> + ... + +The ``target`` element can have an optional ``port`` attribute, which specifies +the port number (starting from 0), and an optional ``type`` attribute: valid +values are, :since:`since 1.0.2` , ``isa-serial`` (usable with x86 guests), +``usb-serial`` (usable whenever USB support is available) and ``pci-serial`` +(usable whenever PCI support is available); :since:`since 3.10.0` , +``spapr-vio-serial`` (usable with ppc64/pseries guests), ``system-serial`` +(usable with aarch64/virt and, :since:`since 4.7.0` , riscv/virt guests) and +``sclp-serial`` (usable with s390 and s390x guests) are available as well. + +:since:`Since 3.10.0` , the ``target`` element can have an optional ``model`` +subelement; valid values for its ``name`` attribute are: ``isa-serial`` (usable +with the ``isa-serial`` target type); ``usb-serial`` (usable with the +``usb-serial`` target type); ``pci-serial`` (usable with the ``pci-serial`` +target type); ``spapr-vty`` (usable with the ``spapr-vio-serial`` target type); +``pl011`` and, :since:`since 4.7.0` , ``16550a`` (usable with the +``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable +with the ``sclp-serial`` 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. + +If any of the attributes is not specified by the user, libvirt will choose a +value suitable for most users. + +Most target types support configuring the guest-visible device address as +`documented above <#elementsAddress>`__; more specifically, acceptable address +types are ``isa`` (for ``isa-serial``), ``usb`` (for ``usb-serial``), ``pci`` +(for ``pci-serial``) and ``spapr-vio`` (for ``spapr-vio-serial``). The +``system-serial`` and ``sclp-serial`` target types don't support specifying an +address. + +For the relationship between serial ports and consoles, `see +below <#elementCharSerialAndConsole>`__. + +:anchor:`<a id="elementCharConsole"/>` + +Console +''''''' + +:: + + ... + <devices> + <!-- Serial console --> + <console type='pty'> + <source path='/dev/pts/2'/> + <target type='serial' port='0'/> + </console> + </devices> + ... + +:: + + ... + <devices> + <!-- KVM virtio console --> + <console type='pty'> + <source path='/dev/pts/5'/> + <target type='virtio' port='0'/> + </console> + </devices> + ... + +The ``console`` element is used to represent interactive serial consoles. +Depending on the type of guest in use and the specifics of the configuration, +the ``console`` element might represent the same device as an existing +``serial`` element or a separate device. + +A ``target`` subelement is supported and works the same way as with the +``serial`` element (`see above <#elementCharSerial>`__ for details). Valid +values for the ``type`` attribute are: ``serial`` (described below); ``virtio`` +(usable whenever VirtIO support is available); ``xen``, ``lxc`` and ``openvz`` +(available when the corresponding hypervisor is in use). ``sclp`` and ``sclplm`` +(usable for s390 and s390x QEMU guests) are supported for compatibility reasons +but should not be used for new guests: use the ``sclpconsole`` and +``sclplmconsole`` target models, respectively, with the ``serial`` element +instead. + +Of the target types listed above, ``serial`` is special in that it doesn't +represents a separate device, but rather the same device as the first ``serial`` +element. Due to this, there can only be a single ``console`` element with target +type ``serial`` per guest. + +Virtio consoles are usually accessible as ``/dev/hvc[0-7]`` from inside the +guest; for more information, see +http://fedoraproject.org/wiki/Features/VirtioSerial. :since:`Since 0.8.3` + +For the relationship between serial ports and consoles, `see +below <#elementCharSerialAndConsole>`__. + +:anchor:`<a id="elementCharSerialAndConsole"/>` + +Relationship between serial ports and consoles +'''''''''''''''''''''''''''''''''''''''''''''' + +Due to hystorical reasons, the ``serial`` and ``console`` elements have +partially overlapping scopes. + +In general, both elements are used to configure one or more serial consoles to +be used for interacting with the guest. The main difference between the two is +that ``serial`` is used for emulated, usually native, serial consoles, whereas +``console`` is used for paravirtualized ones. + +Both emulated and paravirtualized serial consoles have advantages and +disadvantages: + +- emulated serial consoles are usually initialized much earlier than + paravirtualized ones, so they can be used to control the bootloader and + display both firmware and early boot messages; +- on several platforms, there can only be a single emulated serial console per + guest but paravirtualized consoles don't suffer from the same limitation. + +A configuration such as: + +:: + + ... + <devices> + <console type='pty'> + <target type='serial'/> + </console> + <console type='pty'> + <target type='virtio'/> + </console> + </devices> + ... + +will work on any platform and will result in one emulated serial console 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 ``console`` element in their configuration, but if a specific +configuration is desired then both elements should be specified. + +Note that, due to the compatibility concerns mentioned earlier, all the +following configurations: + +:: + + ... + <devices> + <serial type='pty'/> + </devices> + ... + +:: + + ... + <devices> + <console type='pty'/> + </devices> + ... + +:: + + ... + <devices> + <serial type='pty'/> + <console type='pty'/> + </devices> + ... + +will be treated the same and will result in a single emulated serial console +being available to the guest. + +:anchor:`<a id="elementCharChannel"/>` + +Channel +''''''' + +This represents a private communication channel between the host and the guest. + +:: + + ... + <devices> + <channel type='unix'> + <source mode='bind' path='/tmp/guestfwd'/> + <target type='guestfwd' address='10.0.2.1' port='4600'/> + </channel> + + <!-- KVM virtio channel --> + <channel type='pty'> + <target type='virtio' name='arbitrary.virtio.serial.port.name'/> + </channel> + <channel type='unix'> + <source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/> + <target type='virtio' name='org.qemu.guest_agent.0' state='connected'/> + </channel> + <channel type='spicevmc'> + <target type='virtio' name='com.redhat.spice.0'/> + </channel> + </devices> + ... + +This can be implemented in a variety of ways. The specific type of channel is +given in the ``type`` attribute of the ``target`` element. Different channel +types have different ``target`` attributes. + +``guestfwd`` + TCP traffic sent by the guest to a given IP address and port is forwarded to + the channel device on the host. The ``target`` element must have ``address`` + and ``port`` attributes. :since:`Since 0.7.3` +``virtio`` + Paravirtualized virtio channel. Channel is exposed in the guest under + /dev/vport*, and if the optional element ``name`` is specified, + /dev/virtio-ports/$name (for more info, please see + http://fedoraproject.org/wiki/Features/VirtioSerial). The optional element + ``address`` can tie the channel to a particular ``type='virtio-serial'`` + controller, `documented above <#elementsAddress>`__. With qemu, if ``name`` + is "org.qemu.guest_agent.0", then libvirt can interact with a guest agent + installed in the guest, for actions such as guest shutdown or file system + quiescing. :since:`Since 0.7.7, guest agent interaction since 0.9.10` + Moreover, :since:`since 1.0.6` it is possible to have source path auto + generated for virtio unix channels. This is very useful in case of a qemu + guest agent, where users don't usually care about the source path since it's + libvirt who talks to the guest agent. In case users want to utilize this + feature, they should leave ``<source>`` element out. :since:`Since 1.2.11` + the active XML for a virtio channel may contain an optional ``state`` + attribute that reflects whether a process in the guest is active on the + channel. This is an output-only attribute. Possible values for the ``state`` + attribute are ``connected`` and ``disconnected``. +``xen`` + Paravirtualized Xen channel. Channel is exposed in the guest as a Xen console + but identified with a name. Setup and consumption of a Xen channel depends on + software and configuration in the guest (for more info, please see + http://xenbits.xen.org/docs/unstable/misc/channel.txt). Channel source path + semantics are the same as the virtio target type. The ``state`` attribute is + not supported since Xen channels lack the necessary probing mechanism. + :since:`Since 2.3.0` +``spicevmc`` + Paravirtualized SPICE channel. The domain must also have a SPICE server as a + `graphics device <#elementsGraphics>`__, at which point the host piggy-backs + messages across the ``main`` channel. The ``target`` element must be present, + with attribute ``type='virtio'``; an optional attribute ``name`` controls how + the guest will have access to the channel, and defaults to + ``name='com.redhat.spice.0'``. The optional ``address`` element can tie the + channel to a particular ``type='virtio-serial'`` controller. :since:`Since + 0.8.8` + +:anchor:`<a id="elementsCharHostInterface"/>` + +Host interface +^^^^^^^^^^^^^^ + +A character device presents itself to the host as one of the following types. + +:anchor:`<a id="elementsCharSTDIO"/>` + +Domain logfile +'''''''''''''' + +This disables all input on the character device, and sends output into the +virtual machine's logfile + +:: + + ... + <devices> + <console type='stdio'> + <target port='1'/> + </console> + </devices> + ... + +:anchor:`<a id="elementsCharFle"/>` + +Device logfile +'''''''''''''' + +A file is opened and all data sent to the character device is written to the +file. + +:: + + ... + <devices> + <serial type="file"> + <source path="/var/log/vm/vm-serial.log"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharVC"/>` + +Virtual console +''''''''''''''' + +Connects the character device to the graphical framebuffer in a virtual console. +This is typically accessed via a special hotkey sequence such as "ctrl+alt+3" + +:: + + ... + <devices> + <serial type='vc'> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharNull"/>` + +Null device +''''''''''' + +Connects the character device to the void. No data is ever provided to the +input. All data written is discarded. + +:: + + ... + <devices> + <serial type='null'> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharPTY"/>` + +Pseudo TTY +'''''''''' + +A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as 'virsh +console' can connect to interact with the serial port locally. + +:: + + ... + <devices> + <serial type="pty"> + <source path="/dev/pts/3"/> + <target port="1"/> + </serial> + </devices> + ... + +NB special case if <console type='pty'>, then the TTY path is also duplicated as +an attribute tty='/dev/pts/3' on the top level <console> tag. This provides +compat with existing syntax for <console> tags. + +:anchor:`<a id="elementsCharHost"/>` + +Host device proxy +''''''''''''''''' + +The character device is passed through to the underlying physical character +device. The device types must match, eg the emulated serial port should only be +connected to a host serial port - don't connect a serial port to a parallel +port. + +:: + + ... + <devices> + <serial type="dev"> + <source path="/dev/ttyS0"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharPipe"/>` + +Named pipe +'''''''''' + +The character device writes output to a named pipe. See pipe(7) for more info. + +:: + + ... + <devices> + <serial type="pipe"> + <source path="/tmp/mypipe"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharTCP"/>` + +TCP client/server +''''''''''''''''' + +The character device acts as a TCP client connecting to a remote server. + +:: + + ... + <devices> + <serial type="tcp"> + <source mode="connect" host="0.0.0.0" service="2445"/> + <protocol type="raw"/> + <target port="1"/> + </serial> + </devices> + ... + +Or as a TCP server waiting for a client connection. + +:: + + ... + <devices> + <serial type="tcp"> + <source mode="bind" host="127.0.0.1" service="2445"/> + <protocol type="raw"/> + <target port="1"/> + </serial> + </devices> + ... + +Alternatively you can use ``telnet`` instead of ``raw`` TCP in order to utilize +the telnet protocol for the connection. + +:since:`Since 0.8.5,` some hypervisors support use of either ``telnets`` (secure +telnet) or ``tls`` (via secure sockets layer) as the transport protocol for +connections. + +:: + + ... + <devices> + <serial type="tcp"> + <source mode="connect" host="0.0.0.0" service="2445"/> + <protocol type="telnet"/> + <target port="1"/> + </serial> + ... + <serial type="tcp"> + <source mode="bind" host="127.0.0.1" service="2445"/> + <protocol type="telnet"/> + <target port="1"/> + </serial> + </devices> + ... + +:since:`Since 2.4.0,` the optional attribute ``tls`` can be used to control +whether a chardev TCP communication channel would utilize a hypervisor +configured TLS X.509 certificate environment in order to encrypt the data +channel. For the QEMU hypervisor, usage of a TLS environment can be controlled +on the host by the ``chardev_tls`` and ``chardev_tls_x509_cert_dir`` or +``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf. If +``chardev_tls`` is enabled, then unless the ``tls`` attribute is set to "no", +libvirt will use the host configured TLS environment. If ``chardev_tls`` is +disabled, but the ``tls`` attribute is set to "yes", then libvirt will attempt +to use the host TLS environment if either the ``chardev_tls_x509_cert_dir`` or +``default_tls_x509_cert_dir`` TLS directory structure exists. + +:: + + ... + <devices> + <serial type="tcp"> + <source mode='connect' host="127.0.0.1" service="5555" tls="yes"/> + <protocol type="raw"/> + <target port="0"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharUDP"/>` + +UDP network console +''''''''''''''''''' + +The character device acts as a UDP netconsole service, sending and receiving +packets. This is a lossy service. + +:: + + ... + <devices> + <serial type="udp"> + <source mode="bind" host="0.0.0.0" service="2445"/> + <source mode="connect" host="0.0.0.0" service="2445"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharUNIX"/>` + +UNIX domain socket client/server +'''''''''''''''''''''''''''''''' + +The character device acts as a UNIX domain socket server, accepting connections +from local clients. + +:: + + ... + <devices> + <serial type="unix"> + <source mode="bind" path="/tmp/foo"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsCharSpiceport"/>` + +Spice channel +''''''''''''' + +The character device is accessible through spice connection under a channel name +specified in the ``channel`` attribute. :since:`Since 1.2.2` + +Note: depending on the hypervisor, spiceports might (or might not) be enabled on +domains with or without `spice graphics <#elementsGraphics>`__. + +:: + + ... + <devices> + <serial type="spiceport"> + <source channel="org.qemu.console.serial.0"/> + <target port="1"/> + </serial> + </devices> + ... + +:anchor:`<a id="elementsNmdm"/>` + +Nmdm device +''''''''''' + +The nmdm device driver, available on FreeBSD, provides two tty devices connected +together by a virtual null modem cable. :since:`Since 1.2.4` + +:: + + ... + <devices> + <serial type="nmdm"> + <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/> + </serial> + </devices> + ... + +The ``source`` element has these attributes: + +``master`` + Master device of the pair, that is passed to the hypervisor. Device is + specified by a fully qualified path. +``slave`` + Slave device of the pair, that is passed to the clients for connection to the + guest console. Device is specified by a fully qualified path. diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index 8d8d52731e..0e4ea95d3b 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -53,689 +53,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-hub.rst .. include:: formatdomain-devices-graphics.rst .. include:: formatdomain-devices-video.rst - -:anchor:`<a id="elementsConsole"/>` - -Consoles, serial, parallel & channel devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A character device provides a way to interact with the virtual machine. -Paravirtualized consoles, serial ports, parallel ports and channels are all -classed as character devices and so represented using the same syntax. - -:: - - ... - <devices> - <parallel type='pty'> - <source path='/dev/pts/2'/> - <target port='0'/> - </parallel> - <serial type='pty'> - <source path='/dev/pts/3'/> - <target port='0'/> - </serial> - <serial type='file'> - <source path='/tmp/file' append='on'> - <seclabel model='dac' relabel='no'/> - </source> - <target port='0'/> - </serial> - <console type='pty'> - <source path='/dev/pts/4'/> - <target port='0'/> - </console> - <channel type='unix'> - <source mode='bind' path='/tmp/guestfwd'/> - <target type='guestfwd' address='10.0.2.1' port='4600'/> - </channel> - </devices> - ... - -In each of these directives, the top-level element name (parallel, serial, -console, channel) describes how the device is presented to the guest. The guest -interface is configured by the ``target`` element. - -The interface presented to the host is given in the ``type`` attribute of the -top-level element. The host interface is configured by the ``source`` element. - -The ``source`` element may contain an optional ``seclabel`` to override the way -that labelling is done on the socket path. If this element is not present, the -`security label is inherited from the per-domain setting <#seclabel>`__. - -If the interface ``type`` presented to the host is "file", then the ``source`` -element may contain an optional attribute ``append`` that specifies whether or -not the information in the file should be preserved on domain restart. Allowed -values are "on" and "off" (default). :since:`Since 1.3.1` . - -Regardless of the ``type``, character devices can have an optional log file -associated with them. This is expressed via a ``log`` sub-element, with a -``file`` attribute. There can also be an ``append`` attribute which takes the -same values described above. :since:`Since 1.3.3` . - -:: - - ... - <log file="/var/log/libvirt/qemu/guestname-serial0.log" append="off"/> - ... - -Each character device element has an optional sub-element ``<address>`` which -can tie the device to a particular `controller <#elementsControllers>`__ or PCI -slot. - -For character device with type ``unix`` or ``tcp`` the ``source`` has an -optional element ``reconnect`` which configures reconnect timeout if the -connection is lost. There are two attributes, ``enabled`` where possible values -are "yes" and "no" and ``timeout`` which is in seconds. The ``reconnect`` -attribute is valid only for ``connect`` mode. :since:`Since 3.7.0 (QEMU driver -only)` . - -:anchor:`<a id="elementsCharGuestInterface"/>` - -Guest interface -^^^^^^^^^^^^^^^ - -A character device presents itself to the guest as one of the following types. - -:anchor:`<a id="elementCharParallel"/>` - -Parallel port -''''''''''''' - -:: - - ... - <devices> - <parallel type='pty'> - <source path='/dev/pts/2'/> - <target port='0'/> - </parallel> - </devices> - ... - -``target`` can have a ``port`` attribute, which specifies the port number. Ports -are numbered starting from 0. There are usually 0, 1 or 2 parallel ports. - -:anchor:`<a id="elementCharSerial"/>` - -Serial port -''''''''''' - -:: - - ... - <devices> - <!-- Serial port --> - <serial type='pty'> - <source path='/dev/pts/3'/> - <target port='0'/> - </serial> - </devices> - ... - -:: - - ... - <devices> - <!-- USB serial port --> - <serial type='pty'> - <target type='usb-serial' port='0'> - <model name='usb-serial'/> - </target> - <address type='usb' bus='0' port='1'/> - </serial> - </devices> - ... - -The ``target`` element can have an optional ``port`` attribute, which specifies -the port number (starting from 0), and an optional ``type`` attribute: valid -values are, :since:`since 1.0.2` , ``isa-serial`` (usable with x86 guests), -``usb-serial`` (usable whenever USB support is available) and ``pci-serial`` -(usable whenever PCI support is available); :since:`since 3.10.0` , -``spapr-vio-serial`` (usable with ppc64/pseries guests), ``system-serial`` -(usable with aarch64/virt and, :since:`since 4.7.0` , riscv/virt guests) and -``sclp-serial`` (usable with s390 and s390x guests) are available as well. - -:since:`Since 3.10.0` , the ``target`` element can have an optional ``model`` -subelement; valid values for its ``name`` attribute are: ``isa-serial`` (usable -with the ``isa-serial`` target type); ``usb-serial`` (usable with the -``usb-serial`` target type); ``pci-serial`` (usable with the ``pci-serial`` -target type); ``spapr-vty`` (usable with the ``spapr-vio-serial`` target type); -``pl011`` and, :since:`since 4.7.0` , ``16550a`` (usable with the -``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable -with the ``sclp-serial`` 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. - -If any of the attributes is not specified by the user, libvirt will choose a -value suitable for most users. - -Most target types support configuring the guest-visible device address as -`documented above <#elementsAddress>`__; more specifically, acceptable address -types are ``isa`` (for ``isa-serial``), ``usb`` (for ``usb-serial``), ``pci`` -(for ``pci-serial``) and ``spapr-vio`` (for ``spapr-vio-serial``). The -``system-serial`` and ``sclp-serial`` target types don't support specifying an -address. - -For the relationship between serial ports and consoles, `see -below <#elementCharSerialAndConsole>`__. - -:anchor:`<a id="elementCharConsole"/>` - -Console -''''''' - -:: - - ... - <devices> - <!-- Serial console --> - <console type='pty'> - <source path='/dev/pts/2'/> - <target type='serial' port='0'/> - </console> - </devices> - ... - -:: - - ... - <devices> - <!-- KVM virtio console --> - <console type='pty'> - <source path='/dev/pts/5'/> - <target type='virtio' port='0'/> - </console> - </devices> - ... - -The ``console`` element is used to represent interactive serial consoles. -Depending on the type of guest in use and the specifics of the configuration, -the ``console`` element might represent the same device as an existing -``serial`` element or a separate device. - -A ``target`` subelement is supported and works the same way as with the -``serial`` element (`see above <#elementCharSerial>`__ for details). Valid -values for the ``type`` attribute are: ``serial`` (described below); ``virtio`` -(usable whenever VirtIO support is available); ``xen``, ``lxc`` and ``openvz`` -(available when the corresponding hypervisor is in use). ``sclp`` and ``sclplm`` -(usable for s390 and s390x QEMU guests) are supported for compatibility reasons -but should not be used for new guests: use the ``sclpconsole`` and -``sclplmconsole`` target models, respectively, with the ``serial`` element -instead. - -Of the target types listed above, ``serial`` is special in that it doesn't -represents a separate device, but rather the same device as the first ``serial`` -element. Due to this, there can only be a single ``console`` element with target -type ``serial`` per guest. - -Virtio consoles are usually accessible as ``/dev/hvc[0-7]`` from inside the -guest; for more information, see -http://fedoraproject.org/wiki/Features/VirtioSerial. :since:`Since 0.8.3` - -For the relationship between serial ports and consoles, `see -below <#elementCharSerialAndConsole>`__. - -:anchor:`<a id="elementCharSerialAndConsole"/>` - -Relationship between serial ports and consoles -'''''''''''''''''''''''''''''''''''''''''''''' - -Due to hystorical reasons, the ``serial`` and ``console`` elements have -partially overlapping scopes. - -In general, both elements are used to configure one or more serial consoles to -be used for interacting with the guest. The main difference between the two is -that ``serial`` is used for emulated, usually native, serial consoles, whereas -``console`` is used for paravirtualized ones. - -Both emulated and paravirtualized serial consoles have advantages and -disadvantages: - -- emulated serial consoles are usually initialized much earlier than - paravirtualized ones, so they can be used to control the bootloader and - display both firmware and early boot messages; -- on several platforms, there can only be a single emulated serial console per - guest but paravirtualized consoles don't suffer from the same limitation. - -A configuration such as: - -:: - - ... - <devices> - <console type='pty'> - <target type='serial'/> - </console> - <console type='pty'> - <target type='virtio'/> - </console> - </devices> - ... - -will work on any platform and will result in one emulated serial console 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 ``console`` element in their configuration, but if a specific -configuration is desired then both elements should be specified. - -Note that, due to the compatibility concerns mentioned earlier, all the -following configurations: - -:: - - ... - <devices> - <serial type='pty'/> - </devices> - ... - -:: - - ... - <devices> - <console type='pty'/> - </devices> - ... - -:: - - ... - <devices> - <serial type='pty'/> - <console type='pty'/> - </devices> - ... - -will be treated the same and will result in a single emulated serial console -being available to the guest. - -:anchor:`<a id="elementCharChannel"/>` - -Channel -''''''' - -This represents a private communication channel between the host and the guest. - -:: - - ... - <devices> - <channel type='unix'> - <source mode='bind' path='/tmp/guestfwd'/> - <target type='guestfwd' address='10.0.2.1' port='4600'/> - </channel> - - <!-- KVM virtio channel --> - <channel type='pty'> - <target type='virtio' name='arbitrary.virtio.serial.port.name'/> - </channel> - <channel type='unix'> - <source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/> - <target type='virtio' name='org.qemu.guest_agent.0' state='connected'/> - </channel> - <channel type='spicevmc'> - <target type='virtio' name='com.redhat.spice.0'/> - </channel> - </devices> - ... - -This can be implemented in a variety of ways. The specific type of channel is -given in the ``type`` attribute of the ``target`` element. Different channel -types have different ``target`` attributes. - -``guestfwd`` - TCP traffic sent by the guest to a given IP address and port is forwarded to - the channel device on the host. The ``target`` element must have ``address`` - and ``port`` attributes. :since:`Since 0.7.3` -``virtio`` - Paravirtualized virtio channel. Channel is exposed in the guest under - /dev/vport*, and if the optional element ``name`` is specified, - /dev/virtio-ports/$name (for more info, please see - http://fedoraproject.org/wiki/Features/VirtioSerial). The optional element - ``address`` can tie the channel to a particular ``type='virtio-serial'`` - controller, `documented above <#elementsAddress>`__. With qemu, if ``name`` - is "org.qemu.guest_agent.0", then libvirt can interact with a guest agent - installed in the guest, for actions such as guest shutdown or file system - quiescing. :since:`Since 0.7.7, guest agent interaction since 0.9.10` - Moreover, :since:`since 1.0.6` it is possible to have source path auto - generated for virtio unix channels. This is very useful in case of a qemu - guest agent, where users don't usually care about the source path since it's - libvirt who talks to the guest agent. In case users want to utilize this - feature, they should leave ``<source>`` element out. :since:`Since 1.2.11` - the active XML for a virtio channel may contain an optional ``state`` - attribute that reflects whether a process in the guest is active on the - channel. This is an output-only attribute. Possible values for the ``state`` - attribute are ``connected`` and ``disconnected``. -``xen`` - Paravirtualized Xen channel. Channel is exposed in the guest as a Xen console - but identified with a name. Setup and consumption of a Xen channel depends on - software and configuration in the guest (for more info, please see - http://xenbits.xen.org/docs/unstable/misc/channel.txt). Channel source path - semantics are the same as the virtio target type. The ``state`` attribute is - not supported since Xen channels lack the necessary probing mechanism. - :since:`Since 2.3.0` -``spicevmc`` - Paravirtualized SPICE channel. The domain must also have a SPICE server as a - `graphics device <#elementsGraphics>`__, at which point the host piggy-backs - messages across the ``main`` channel. The ``target`` element must be present, - with attribute ``type='virtio'``; an optional attribute ``name`` controls how - the guest will have access to the channel, and defaults to - ``name='com.redhat.spice.0'``. The optional ``address`` element can tie the - channel to a particular ``type='virtio-serial'`` controller. :since:`Since - 0.8.8` - -:anchor:`<a id="elementsCharHostInterface"/>` - -Host interface -^^^^^^^^^^^^^^ - -A character device presents itself to the host as one of the following types. - -:anchor:`<a id="elementsCharSTDIO"/>` - -Domain logfile -'''''''''''''' - -This disables all input on the character device, and sends output into the -virtual machine's logfile - -:: - - ... - <devices> - <console type='stdio'> - <target port='1'/> - </console> - </devices> - ... - -:anchor:`<a id="elementsCharFle"/>` - -Device logfile -'''''''''''''' - -A file is opened and all data sent to the character device is written to the -file. - -:: - - ... - <devices> - <serial type="file"> - <source path="/var/log/vm/vm-serial.log"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharVC"/>` - -Virtual console -''''''''''''''' - -Connects the character device to the graphical framebuffer in a virtual console. -This is typically accessed via a special hotkey sequence such as "ctrl+alt+3" - -:: - - ... - <devices> - <serial type='vc'> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharNull"/>` - -Null device -''''''''''' - -Connects the character device to the void. No data is ever provided to the -input. All data written is discarded. - -:: - - ... - <devices> - <serial type='null'> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharPTY"/>` - -Pseudo TTY -'''''''''' - -A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as 'virsh -console' can connect to interact with the serial port locally. - -:: - - ... - <devices> - <serial type="pty"> - <source path="/dev/pts/3"/> - <target port="1"/> - </serial> - </devices> - ... - -NB special case if <console type='pty'>, then the TTY path is also duplicated as -an attribute tty='/dev/pts/3' on the top level <console> tag. This provides -compat with existing syntax for <console> tags. - -:anchor:`<a id="elementsCharHost"/>` - -Host device proxy -''''''''''''''''' - -The character device is passed through to the underlying physical character -device. The device types must match, eg the emulated serial port should only be -connected to a host serial port - don't connect a serial port to a parallel -port. - -:: - - ... - <devices> - <serial type="dev"> - <source path="/dev/ttyS0"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharPipe"/>` - -Named pipe -'''''''''' - -The character device writes output to a named pipe. See pipe(7) for more info. - -:: - - ... - <devices> - <serial type="pipe"> - <source path="/tmp/mypipe"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharTCP"/>` - -TCP client/server -''''''''''''''''' - -The character device acts as a TCP client connecting to a remote server. - -:: - - ... - <devices> - <serial type="tcp"> - <source mode="connect" host="0.0.0.0" service="2445"/> - <protocol type="raw"/> - <target port="1"/> - </serial> - </devices> - ... - -Or as a TCP server waiting for a client connection. - -:: - - ... - <devices> - <serial type="tcp"> - <source mode="bind" host="127.0.0.1" service="2445"/> - <protocol type="raw"/> - <target port="1"/> - </serial> - </devices> - ... - -Alternatively you can use ``telnet`` instead of ``raw`` TCP in order to utilize -the telnet protocol for the connection. - -:since:`Since 0.8.5,` some hypervisors support use of either ``telnets`` (secure -telnet) or ``tls`` (via secure sockets layer) as the transport protocol for -connections. - -:: - - ... - <devices> - <serial type="tcp"> - <source mode="connect" host="0.0.0.0" service="2445"/> - <protocol type="telnet"/> - <target port="1"/> - </serial> - ... - <serial type="tcp"> - <source mode="bind" host="127.0.0.1" service="2445"/> - <protocol type="telnet"/> - <target port="1"/> - </serial> - </devices> - ... - -:since:`Since 2.4.0,` the optional attribute ``tls`` can be used to control -whether a chardev TCP communication channel would utilize a hypervisor -configured TLS X.509 certificate environment in order to encrypt the data -channel. For the QEMU hypervisor, usage of a TLS environment can be controlled -on the host by the ``chardev_tls`` and ``chardev_tls_x509_cert_dir`` or -``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf. If -``chardev_tls`` is enabled, then unless the ``tls`` attribute is set to "no", -libvirt will use the host configured TLS environment. If ``chardev_tls`` is -disabled, but the ``tls`` attribute is set to "yes", then libvirt will attempt -to use the host TLS environment if either the ``chardev_tls_x509_cert_dir`` or -``default_tls_x509_cert_dir`` TLS directory structure exists. - -:: - - ... - <devices> - <serial type="tcp"> - <source mode='connect' host="127.0.0.1" service="5555" tls="yes"/> - <protocol type="raw"/> - <target port="0"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharUDP"/>` - -UDP network console -''''''''''''''''''' - -The character device acts as a UDP netconsole service, sending and receiving -packets. This is a lossy service. - -:: - - ... - <devices> - <serial type="udp"> - <source mode="bind" host="0.0.0.0" service="2445"/> - <source mode="connect" host="0.0.0.0" service="2445"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharUNIX"/>` - -UNIX domain socket client/server -'''''''''''''''''''''''''''''''' - -The character device acts as a UNIX domain socket server, accepting connections -from local clients. - -:: - - ... - <devices> - <serial type="unix"> - <source mode="bind" path="/tmp/foo"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsCharSpiceport"/>` - -Spice channel -''''''''''''' - -The character device is accessible through spice connection under a channel name -specified in the ``channel`` attribute. :since:`Since 1.2.2` - -Note: depending on the hypervisor, spiceports might (or might not) be enabled on -domains with or without `spice graphics <#elementsGraphics>`__. - -:: - - ... - <devices> - <serial type="spiceport"> - <source channel="org.qemu.console.serial.0"/> - <target port="1"/> - </serial> - </devices> - ... - -:anchor:`<a id="elementsNmdm"/>` - -Nmdm device -''''''''''' - -The nmdm device driver, available on FreeBSD, provides two tty devices connected -together by a virtual null modem cable. :since:`Since 1.2.4` - -:: - - ... - <devices> - <serial type="nmdm"> - <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/> - </serial> - </devices> - ... - -The ``source`` element has these attributes: - -``master`` - Master device of the pair, that is passed to the hypervisor. Device is - specified by a fully qualified path. -``slave`` - Slave device of the pair, that is passed to the clients for connection to the - guest console. Device is specified by a fully qualified path. +.. include:: formatdomain-devices-chardev.rst :anchor:`<a id="elementsSound"/>` diff --git a/docs/meson.build b/docs/meson.build index 56791e3258..440356f7ac 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -138,6 +138,7 @@ docs_rst_files = [ 'formatdomain-devices-hub.rst', 'formatdomain-devices-graphics.rst', 'formatdomain-devices-video.rst', + 'formatdomain-devices-chardev.rst', ] }, { 'name': 'hacking' }, -- 2.26.2