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

Peter Krempa pkrempa at redhat.com
Thu Jul 23 13:21:26 UTC 2020


Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 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




More information about the libvir-list mailing list