[PATCH 19/32] docs: formatdomain-devices: Split out <graphics>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-graphics.rst | 244 ++++++++++++++++++++++++ docs/formatdomain-devices.rst | 246 +------------------------ docs/meson.build | 1 + 3 files changed, 246 insertions(+), 245 deletions(-) create mode 100644 docs/formatdomain-devices-graphics.rst diff --git a/docs/formatdomain-devices-graphics.rst b/docs/formatdomain-devices-graphics.rst new file mode 100644 index 0000000000..9373cd34bd --- /dev/null +++ b/docs/formatdomain-devices-graphics.rst @@ -0,0 +1,244 @@ +:anchor:`<a id="elementsGraphics"/>` + +Graphical framebuffers +~~~~~~~~~~~~~~~~~~~~~~ + +A graphics device allows for graphical interaction with the guest OS. A guest +will typically have either a framebuffer or a text console configured to allow +interaction with the admin. + +:: + + ... + <devices> + <graphics type='sdl' display=':0.0'/> + <graphics type='vnc' port='5904' sharePolicy='allow-exclusive'> + <listen type='address' address='1.2.3.4'/> + </graphics> + <graphics type='rdp' autoport='yes' multiUser='yes' /> + <graphics type='desktop' fullscreen='yes'/> + <graphics type='spice'> + <listen type='network' network='rednet'/> + </graphics> + </devices> + ... + +``graphics`` + The ``graphics`` element has a mandatory ``type`` attribute which takes the + value ``sdl``, ``vnc``, ``spice``, ``rdp``, ``desktop`` or ``egl-headless``: + + ``sdl`` + This displays a window on the host desktop, it can take 3 optional + arguments: a ``display`` attribute for the display to use, an ``xauth`` + attribute for the authentication identifier, and an optional + ``fullscreen`` attribute accepting values ``yes`` or ``no``. + + You can use a ``gl`` with the ``enable="yes"`` property to enable OpenGL + support in SDL. Likewise you can explicitly disable OpenGL support with + ``enable="no"``. + + ``vnc`` + Starts a VNC server. The ``port`` attribute specifies the TCP port number + (with -1 as legacy syntax indicating that it should be auto-allocated). + The ``autoport`` attribute is the new preferred syntax for indicating + auto-allocation of the TCP port to use. The ``passwd`` attribute provides + a VNC password in clear text. If the ``passwd`` attribute is set to an + empty string, then VNC access is disabled. The ``keymap`` attribute + specifies the keymap to use. It is possible to set a limit on the validity + of the password by giving a timestamp + ``passwdValidTo='2010-04-09T15:51:00'`` assumed to be in UTC. The + ``connected`` attribute allows control of connected client during password + changes. VNC accepts ``keep`` value only :since:`since 0.9.3` . NB, this + may not be supported by all hypervisors. + + The optional ``sharePolicy`` attribute specifies vnc server display + sharing policy. ``allow-exclusive`` allows clients to ask for exclusive + access by dropping other connections. Connecting multiple clients in + parallel requires all clients asking for a shared session (vncviewer: + -Shared switch). This is the default value. ``force-shared`` disables + exclusive client access, every connection has to specify -Shared switch + for vncviewer. ``ignore`` welcomes every connection unconditionally + :since:`since 1.0.6` . + + Rather than using listen/port, QEMU supports a ``socket`` attribute for + listening on a unix domain socket path :since:`Since 0.8.8` . + + For VNC WebSocket functionality, ``websocket`` attribute may be used to + specify port to listen on (with -1 meaning auto-allocation and + ``autoport`` having no effect due to security reasons) :since:`Since + 1.0.6` . + + Although VNC doesn't support OpenGL natively, it can be paired with + graphics type ``egl-headless`` (see below) which will instruct QEMU to + open and use drm nodes for OpenGL rendering. + + ``spice`` :since:`Since 0.8.6` + Starts a SPICE server. The ``port`` attribute specifies the TCP port + number (with -1 as legacy syntax indicating that it should be + auto-allocated), while ``tlsPort`` gives an alternative secure port + number. The ``autoport`` attribute is the new preferred syntax for + indicating auto-allocation of needed port numbers. The ``passwd`` + attribute provides a SPICE password in clear text. If the ``passwd`` + attribute is set to an empty string, then SPICE access is disabled. The + ``keymap`` attribute specifies the keymap to use. It is possible to set a + limit on the validity of the password by giving a timestamp + ``passwdValidTo='2010-04-09T15:51:00'`` assumed to be in UTC. + + The ``connected`` attribute allows control of connected client during + password changes. SPICE accepts ``keep`` to keep client connected, + ``disconnect`` to disconnect client and ``fail`` to fail changing password + . NB, this may not be supported by all hypervisors. :since:`Since 0.9.3` + + The ``defaultMode`` attribute sets the default channel security policy, + valid values are ``secure``, ``insecure`` and the default ``any`` (which + is secure if possible, but falls back to insecure rather than erroring out + if no secure path is available). :since:`Since 0.9.12` + + When SPICE has both a normal and TLS secured TCP port configured, it can + be desirable to restrict what channels can be run on each port. This is + achieved by adding one or more ``<channel>`` elements inside the main + ``<graphics>`` element and setting the ``mode`` attribute to either + ``secure`` or ``insecure``. Setting the mode attribute overrides the + default value as set by the ``defaultMode`` attribute. (Note that + specifying ``any`` as mode discards the entry as the channel would inherit + the default mode anyways.) Valid channel names include ``main``, + ``display``, ``inputs``, ``cursor``, ``playback``, ``record`` (all + :since:` since 0.8.6` ); ``smartcard`` ( :since:`since 0.8.8` ); and + ``usbredir`` ( :since:`since 0.9.12` ). + + :: + + <graphics type='spice' port='-1' tlsPort='-1' autoport='yes'> + <channel name='main' mode='secure'/> + <channel name='record' mode='insecure'/> + <image compression='auto_glz'/> + <streaming mode='filter'/> + <clipboard copypaste='no'/> + <mouse mode='client'/> + <filetransfer enable='no'/> + <gl enable='yes' rendernode='/dev/dri/by-path/pci-0000:00:02.0-render'/> + </graphics> + + Spice supports variable compression settings for audio, images and + streaming. These settings are accessible via the ``compression`` attribute + in all following elements: ``image`` to set image compression (accepts + ``auto_glz``, ``auto_lz``, ``quic``, ``glz``, ``lz``, ``off``), ``jpeg`` + for JPEG compression for images over wan (accepts ``auto``, ``never``, + ``always``), ``zlib`` for configuring wan image compression (accepts + ``auto``, ``never``, ``always``) and ``playback`` for enabling audio + stream compression (accepts ``on`` or ``off``). :since:`Since 0.9.1` + + Streaming mode is set by the ``streaming`` element, settings its ``mode`` + attribute to one of ``filter``, ``all`` or ``off``. :since:`Since 0.9.2` + + Copy & Paste functionality (via Spice agent) is set by the ``clipboard`` + element. It is enabled by default, and can be disabled by setting the + ``copypaste`` property to ``no``. :since:`Since 0.9.3` + + Mouse mode is set by the ``mouse`` element, setting its ``mode`` attribute + to one of ``server`` or ``client``. If no mode is specified, the qemu + default will be used (client mode). :since:`Since 0.9.11` + + File transfer functionality (via Spice agent) is set using the + ``filetransfer`` element. It is enabled by default, and can be disabled by + setting the ``enable`` property to ``no``. :since:`Since 1.2.2` + + Spice may provide accelerated server-side rendering with OpenGL. You can + enable or disable OpenGL support explicitly with the ``gl`` element, by + setting the ``enable`` property. (QEMU only, :since:`since 1.3.3` ). Note + that this only works locally, since this requires usage of UNIX sockets, + i.e. using ``listen`` types 'socket' or 'none'. For accelerated OpenGL + with remote support, consider pairing this element with type + ``egl-headless`` (see below). However, this will deliver weaker + performance compared to native Spice OpenGL support. + + By default, QEMU will pick the first available GPU DRM render node. You + may specify a DRM render node path to use instead. (QEMU only, + :since:`since 3.1.0` ). + + ``rdp`` + Starts a RDP server. The ``port`` attribute specifies the TCP port number + (with -1 as legacy syntax indicating that it should be auto-allocated). + The ``autoport`` attribute is the new preferred syntax for indicating + auto-allocation of the TCP port to use. In the VirtualBox driver, the + ``autoport`` will make the hypervisor pick available port from 3389-3689 + range when the VM is started. The chosen port will be reflected in the + ``port`` attribute. The ``multiUser`` attribute is a boolean deciding + whether multiple simultaneous connections to the VM are permitted. The + ``replaceUser`` attribute is a boolean deciding whether the existing + connection must be dropped and a new connection must be established by the + VRDP server, when a new client connects in single connection mode. + + ``desktop`` + This value is reserved for VirtualBox domains for the moment. It displays + a window on the host desktop, similarly to "sdl", but using the VirtualBox + viewer. Just like "sdl", it accepts the optional attributes ``display`` + and ``fullscreen``. + + ``egl-headless`` :since:`Since 4.6.0` + This display type provides support for an OpenGL accelerated display + accessible both locally and remotely (for comparison, Spice's native + OpenGL support only works locally using UNIX sockets at the moment, but + has better performance). Since this display type doesn't provide any + window or graphical console like the other types, for practical reasons it + should be paired with either ``vnc`` or ``spice`` graphics types. This + display type is only supported by QEMU domains (needs QEMU :since:`2.10` + or newer). :since:`5.0.0` this element accepts a ``<gl/>`` sub-element + with an optional attribute ``rendernode`` which can be used to specify an + absolute path to a host's DRI device to be used for OpenGL rendering. + + :: + + <graphics type='spice' autoport='yes'/> + <graphics type='egl-headless'> + <gl rendernode='/dev/dri/renderD128'/> + </graphics> + +Graphics device uses a ``<listen>`` to set up where the device should listen for +clients. It has a mandatory attribute ``type`` which specifies the listen type. +Only ``vnc``, ``spice`` and ``rdp`` supports ``<listen>`` element. :since:`Since +0.9.4` . Available types are: + +``address`` + Tells a graphics device to use an address specified in the ``address`` + attribute, which will contain either an IP address or hostname (which will be + resolved to an IP address via a DNS query) to listen on. + + It is possible to omit the ``address`` attribute in order to use an address + from config files :since:`Since 1.3.5` . + + The ``address`` attribute is duplicated as ``listen`` attribute in + ``graphics`` element for backward compatibility. If both are provided they + must be equal. + +``network`` + This is used to specify an existing network in the ``network`` attribute from + libvirt's list of configured networks. The named network configuration will + be examined to determine an appropriate listen address and the address will + be stored in live XML in ``address`` attribute. For example, if the network + has an IPv4 address in its configuration (e.g. if it has a forward type of + ``route``, ``nat``, or no forward type (isolated)), the first IPv4 address + listed in the network's configuration will be used. If the network is + describing a host bridge, the first IPv4 address associated with that bridge + device will be used, and if the network is describing one of the 'direct' + (macvtap) modes, the first IPv4 address of the first forward dev will be + used. + +``socket`` :since:`since 2.0.0 (QEMU only)` + This listen type tells a graphics server to listen on unix socket. Attribute + ``socket`` contains a path to unix socket. If this attribute is omitted + libvirt will generate this path for you. Supported by graphics type ``vnc`` + and ``spice``. + + For ``vnc`` graphics be backward compatible the ``socket`` attribute of first + ``listen`` element is duplicated as ``socket`` attribute in ``graphics`` + element. If ``graphics`` element contains a ``socket`` attribute all + ``listen`` elements are ignored. + +``none`` :since:`since 2.0.0 (QEMU only)` + This listen type doesn't have any other attribute. Libvirt supports passing a + file descriptor through our APIs virDomainOpenGraphics() and + virDomainOpenGraphicsFD(). No other listen types are allowed if this one is + used and the graphics device doesn't listen anywhere. You need to use one of + the two APIs to pass a FD to QEMU in order to connect to this graphics + device. Supported by graphics type ``vnc`` and ``spice``. diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index 5d2cca26af..d2aba7ba28 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -51,251 +51,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-interface.rst .. include:: formatdomain-devices-input.rst .. include:: formatdomain-devices-hub.rst - -:anchor:`<a id="elementsGraphics"/>` - -Graphical framebuffers -~~~~~~~~~~~~~~~~~~~~~~ - -A graphics device allows for graphical interaction with the guest OS. A guest -will typically have either a framebuffer or a text console configured to allow -interaction with the admin. - -:: - - ... - <devices> - <graphics type='sdl' display=':0.0'/> - <graphics type='vnc' port='5904' sharePolicy='allow-exclusive'> - <listen type='address' address='1.2.3.4'/> - </graphics> - <graphics type='rdp' autoport='yes' multiUser='yes' /> - <graphics type='desktop' fullscreen='yes'/> - <graphics type='spice'> - <listen type='network' network='rednet'/> - </graphics> - </devices> - ... - -``graphics`` - The ``graphics`` element has a mandatory ``type`` attribute which takes the - value ``sdl``, ``vnc``, ``spice``, ``rdp``, ``desktop`` or ``egl-headless``: - - ``sdl`` - This displays a window on the host desktop, it can take 3 optional - arguments: a ``display`` attribute for the display to use, an ``xauth`` - attribute for the authentication identifier, and an optional - ``fullscreen`` attribute accepting values ``yes`` or ``no``. - - You can use a ``gl`` with the ``enable="yes"`` property to enable OpenGL - support in SDL. Likewise you can explicitly disable OpenGL support with - ``enable="no"``. - - ``vnc`` - Starts a VNC server. The ``port`` attribute specifies the TCP port number - (with -1 as legacy syntax indicating that it should be auto-allocated). - The ``autoport`` attribute is the new preferred syntax for indicating - auto-allocation of the TCP port to use. The ``passwd`` attribute provides - a VNC password in clear text. If the ``passwd`` attribute is set to an - empty string, then VNC access is disabled. The ``keymap`` attribute - specifies the keymap to use. It is possible to set a limit on the validity - of the password by giving a timestamp - ``passwdValidTo='2010-04-09T15:51:00'`` assumed to be in UTC. The - ``connected`` attribute allows control of connected client during password - changes. VNC accepts ``keep`` value only :since:`since 0.9.3` . NB, this - may not be supported by all hypervisors. - - The optional ``sharePolicy`` attribute specifies vnc server display - sharing policy. ``allow-exclusive`` allows clients to ask for exclusive - access by dropping other connections. Connecting multiple clients in - parallel requires all clients asking for a shared session (vncviewer: - -Shared switch). This is the default value. ``force-shared`` disables - exclusive client access, every connection has to specify -Shared switch - for vncviewer. ``ignore`` welcomes every connection unconditionally - :since:`since 1.0.6` . - - Rather than using listen/port, QEMU supports a ``socket`` attribute for - listening on a unix domain socket path :since:`Since 0.8.8` . - - For VNC WebSocket functionality, ``websocket`` attribute may be used to - specify port to listen on (with -1 meaning auto-allocation and - ``autoport`` having no effect due to security reasons) :since:`Since - 1.0.6` . - - Although VNC doesn't support OpenGL natively, it can be paired with - graphics type ``egl-headless`` (see below) which will instruct QEMU to - open and use drm nodes for OpenGL rendering. - - ``spice`` :since:`Since 0.8.6` - Starts a SPICE server. The ``port`` attribute specifies the TCP port - number (with -1 as legacy syntax indicating that it should be - auto-allocated), while ``tlsPort`` gives an alternative secure port - number. The ``autoport`` attribute is the new preferred syntax for - indicating auto-allocation of needed port numbers. The ``passwd`` - attribute provides a SPICE password in clear text. If the ``passwd`` - attribute is set to an empty string, then SPICE access is disabled. The - ``keymap`` attribute specifies the keymap to use. It is possible to set a - limit on the validity of the password by giving a timestamp - ``passwdValidTo='2010-04-09T15:51:00'`` assumed to be in UTC. - - The ``connected`` attribute allows control of connected client during - password changes. SPICE accepts ``keep`` to keep client connected, - ``disconnect`` to disconnect client and ``fail`` to fail changing password - . NB, this may not be supported by all hypervisors. :since:`Since 0.9.3` - - The ``defaultMode`` attribute sets the default channel security policy, - valid values are ``secure``, ``insecure`` and the default ``any`` (which - is secure if possible, but falls back to insecure rather than erroring out - if no secure path is available). :since:`Since 0.9.12` - - When SPICE has both a normal and TLS secured TCP port configured, it can - be desirable to restrict what channels can be run on each port. This is - achieved by adding one or more ``<channel>`` elements inside the main - ``<graphics>`` element and setting the ``mode`` attribute to either - ``secure`` or ``insecure``. Setting the mode attribute overrides the - default value as set by the ``defaultMode`` attribute. (Note that - specifying ``any`` as mode discards the entry as the channel would inherit - the default mode anyways.) Valid channel names include ``main``, - ``display``, ``inputs``, ``cursor``, ``playback``, ``record`` (all - :since:` since 0.8.6` ); ``smartcard`` ( :since:`since 0.8.8` ); and - ``usbredir`` ( :since:`since 0.9.12` ). - - :: - - <graphics type='spice' port='-1' tlsPort='-1' autoport='yes'> - <channel name='main' mode='secure'/> - <channel name='record' mode='insecure'/> - <image compression='auto_glz'/> - <streaming mode='filter'/> - <clipboard copypaste='no'/> - <mouse mode='client'/> - <filetransfer enable='no'/> - <gl enable='yes' rendernode='/dev/dri/by-path/pci-0000:00:02.0-render'/> - </graphics> - - Spice supports variable compression settings for audio, images and - streaming. These settings are accessible via the ``compression`` attribute - in all following elements: ``image`` to set image compression (accepts - ``auto_glz``, ``auto_lz``, ``quic``, ``glz``, ``lz``, ``off``), ``jpeg`` - for JPEG compression for images over wan (accepts ``auto``, ``never``, - ``always``), ``zlib`` for configuring wan image compression (accepts - ``auto``, ``never``, ``always``) and ``playback`` for enabling audio - stream compression (accepts ``on`` or ``off``). :since:`Since 0.9.1` - - Streaming mode is set by the ``streaming`` element, settings its ``mode`` - attribute to one of ``filter``, ``all`` or ``off``. :since:`Since 0.9.2` - - Copy & Paste functionality (via Spice agent) is set by the ``clipboard`` - element. It is enabled by default, and can be disabled by setting the - ``copypaste`` property to ``no``. :since:`Since 0.9.3` - - Mouse mode is set by the ``mouse`` element, setting its ``mode`` attribute - to one of ``server`` or ``client``. If no mode is specified, the qemu - default will be used (client mode). :since:`Since 0.9.11` - - File transfer functionality (via Spice agent) is set using the - ``filetransfer`` element. It is enabled by default, and can be disabled by - setting the ``enable`` property to ``no``. :since:`Since 1.2.2` - - Spice may provide accelerated server-side rendering with OpenGL. You can - enable or disable OpenGL support explicitly with the ``gl`` element, by - setting the ``enable`` property. (QEMU only, :since:`since 1.3.3` ). Note - that this only works locally, since this requires usage of UNIX sockets, - i.e. using ``listen`` types 'socket' or 'none'. For accelerated OpenGL - with remote support, consider pairing this element with type - ``egl-headless`` (see below). However, this will deliver weaker - performance compared to native Spice OpenGL support. - - By default, QEMU will pick the first available GPU DRM render node. You - may specify a DRM render node path to use instead. (QEMU only, - :since:`since 3.1.0` ). - - ``rdp`` - Starts a RDP server. The ``port`` attribute specifies the TCP port number - (with -1 as legacy syntax indicating that it should be auto-allocated). - The ``autoport`` attribute is the new preferred syntax for indicating - auto-allocation of the TCP port to use. In the VirtualBox driver, the - ``autoport`` will make the hypervisor pick available port from 3389-3689 - range when the VM is started. The chosen port will be reflected in the - ``port`` attribute. The ``multiUser`` attribute is a boolean deciding - whether multiple simultaneous connections to the VM are permitted. The - ``replaceUser`` attribute is a boolean deciding whether the existing - connection must be dropped and a new connection must be established by the - VRDP server, when a new client connects in single connection mode. - - ``desktop`` - This value is reserved for VirtualBox domains for the moment. It displays - a window on the host desktop, similarly to "sdl", but using the VirtualBox - viewer. Just like "sdl", it accepts the optional attributes ``display`` - and ``fullscreen``. - - ``egl-headless`` :since:`Since 4.6.0` - This display type provides support for an OpenGL accelerated display - accessible both locally and remotely (for comparison, Spice's native - OpenGL support only works locally using UNIX sockets at the moment, but - has better performance). Since this display type doesn't provide any - window or graphical console like the other types, for practical reasons it - should be paired with either ``vnc`` or ``spice`` graphics types. This - display type is only supported by QEMU domains (needs QEMU :since:`2.10` - or newer). :since:`5.0.0` this element accepts a ``<gl/>`` sub-element - with an optional attribute ``rendernode`` which can be used to specify an - absolute path to a host's DRI device to be used for OpenGL rendering. - - :: - - <graphics type='spice' autoport='yes'/> - <graphics type='egl-headless'> - <gl rendernode='/dev/dri/renderD128'/> - </graphics> - -Graphics device uses a ``<listen>`` to set up where the device should listen for -clients. It has a mandatory attribute ``type`` which specifies the listen type. -Only ``vnc``, ``spice`` and ``rdp`` supports ``<listen>`` element. :since:`Since -0.9.4` . Available types are: - -``address`` - Tells a graphics device to use an address specified in the ``address`` - attribute, which will contain either an IP address or hostname (which will be - resolved to an IP address via a DNS query) to listen on. - - It is possible to omit the ``address`` attribute in order to use an address - from config files :since:`Since 1.3.5` . - - The ``address`` attribute is duplicated as ``listen`` attribute in - ``graphics`` element for backward compatibility. If both are provided they - must be equal. - -``network`` - This is used to specify an existing network in the ``network`` attribute from - libvirt's list of configured networks. The named network configuration will - be examined to determine an appropriate listen address and the address will - be stored in live XML in ``address`` attribute. For example, if the network - has an IPv4 address in its configuration (e.g. if it has a forward type of - ``route``, ``nat``, or no forward type (isolated)), the first IPv4 address - listed in the network's configuration will be used. If the network is - describing a host bridge, the first IPv4 address associated with that bridge - device will be used, and if the network is describing one of the 'direct' - (macvtap) modes, the first IPv4 address of the first forward dev will be - used. - -``socket`` :since:`since 2.0.0 (QEMU only)` - This listen type tells a graphics server to listen on unix socket. Attribute - ``socket`` contains a path to unix socket. If this attribute is omitted - libvirt will generate this path for you. Supported by graphics type ``vnc`` - and ``spice``. - - For ``vnc`` graphics be backward compatible the ``socket`` attribute of first - ``listen`` element is duplicated as ``socket`` attribute in ``graphics`` - element. If ``graphics`` element contains a ``socket`` attribute all - ``listen`` elements are ignored. - -``none`` :since:`since 2.0.0 (QEMU only)` - This listen type doesn't have any other attribute. Libvirt supports passing a - file descriptor through our APIs virDomainOpenGraphics() and - virDomainOpenGraphicsFD(). No other listen types are allowed if this one is - used and the graphics device doesn't listen anywhere. You need to use one of - the two APIs to pass a FD to QEMU in order to connect to this graphics - device. Supported by graphics type ``vnc`` and ``spice``. +.. include:: formatdomain-devices-graphics.rst :anchor:`<a id="elementsVideo"/>` diff --git a/docs/meson.build b/docs/meson.build index 8657a57632..f26754852d 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -136,6 +136,7 @@ docs_rst_files = [ 'formatdomain-devices-interface.rst', 'formatdomain-devices-input.rst', 'formatdomain-devices-hub.rst', + 'formatdomain-devices-graphics.rst', ] }, { 'name': 'hacking' }, -- 2.26.2