mirror of
https://github.com/libvirt/libvirt.git
synced 2025-02-25 18:55:26 -06:00
docs: rewrite graphics XML documentation
This cleanups the documentation, reformat some of the paragraphs to use <p> instead of </br> and rewrites the listen part to be more extendable. Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
This commit is contained in:
Pavel Hrdina
parent
71ea10851d
commit
f037a955a7
@ -4943,108 +4943,113 @@ qemu-kvm -net nic,model=? /dev/null
|
|||||||
|
|
||||||
<dl>
|
<dl>
|
||||||
<dt><code>graphics</code></dt>
|
<dt><code>graphics</code></dt>
|
||||||
<dd>The <code>graphics</code> element has a mandatory <code>type</code>
|
<dd>
|
||||||
attribute which takes the value "sdl", "vnc", "spice", "rdp" or
|
<p>
|
||||||
"desktop":
|
The <code>graphics</code> element has a mandatory <code>type</code>
|
||||||
|
attribute which takes the value <code>sdl</code>, <code>vnc</code>,
|
||||||
|
<code>spice</code>, <code>rdp</code> or <code>desktop</code>:
|
||||||
|
</p>
|
||||||
<dl>
|
<dl>
|
||||||
<dt><code>"sdl"</code></dt>
|
<dt><code>"sdl"</code></dt>
|
||||||
<dd>
|
<dd>
|
||||||
This displays a window on the host desktop, it can take 3
|
<p>
|
||||||
optional arguments: a <code>display</code> attribute for
|
This displays a window on the host desktop, it can take 3 optional
|
||||||
the display to use, an <code>xauth</code> attribute for
|
arguments: a <code>display</code> attribute for the display to use,
|
||||||
the authentication identifier, and an
|
an <code>xauth</code> attribute for the authentication identifier,
|
||||||
optional <code>fullscreen</code> attribute accepting
|
and an optional <code>fullscreen</code> attribute accepting values
|
||||||
values 'yes' or 'no'.
|
<code>yes</code> or <code>no</code>.
|
||||||
|
</p>
|
||||||
</dd>
|
</dd>
|
||||||
<dt><code>"vnc"</code></dt>
|
<dt><code>"vnc"</code></dt>
|
||||||
<dd>
|
|
||||||
Starts a VNC server. The <code>port</code> attribute
|
|
||||||
specifies the TCP port number (with -1 as legacy syntax
|
|
||||||
indicating that it should be
|
|
||||||
auto-allocated). The <code>autoport</code> attribute is
|
|
||||||
the new preferred syntax for indicating autoallocation of
|
|
||||||
the TCP port to use. The <code>listen</code> attribute is
|
|
||||||
an IP address for the server to listen
|
|
||||||
on. The <code>passwd</code> attribute provides a VNC
|
|
||||||
password in clear text. The <code>keymap</code> attribute
|
|
||||||
specifies the keymap to use. It is possible to set a limit
|
|
||||||
on the validity of the password be giving an
|
|
||||||
timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
|
|
||||||
assumed to be in UTC. The <code>connected</code> attribute
|
|
||||||
allows control of connected client during password changes.
|
|
||||||
VNC accepts <code>keep</code> value only.
|
|
||||||
<span class="since">since 0.9.3</span>
|
|
||||||
NB, this may not be supported by all hypervisors.<br/>
|
|
||||||
The optional <code>sharePolicy</code> 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
|
|
||||||
<span class="since">since 1.0.6</span>. <br/> <br/>
|
|
||||||
Rather than using listen/port, QEMU supports a
|
|
||||||
<code>socket</code> attribute for listening on a unix
|
|
||||||
domain socket path.<span class="since">Since 0.8.8</span>
|
|
||||||
|
|
||||||
For VNC WebSocket functionality, <code>websocket</code>
|
|
||||||
attribute may be used to specify port to listen on (with
|
|
||||||
-1 meaning auto-allocation and <code>autoport</code>
|
|
||||||
having no effect due to security reasons).
|
|
||||||
<span class="since">Since 1.0.6</span>
|
|
||||||
</dd>
|
|
||||||
<dt><code>"spice"</code></dt>
|
|
||||||
<dd>
|
<dd>
|
||||||
<p>
|
<p>
|
||||||
Starts a SPICE server. The <code>port</code> attribute
|
Starts a VNC server. The <code>port</code> attribute specifies
|
||||||
specifies the TCP port number (with -1 as legacy syntax
|
the TCP port number (with -1 as legacy syntax indicating that it
|
||||||
indicating that it should be auto-allocated),
|
should be auto-allocated). The <code>autoport</code> attribute is
|
||||||
while <code>tlsPort</code> gives an alternative secure
|
the new preferred syntax for indicating auto-allocation of the TCP
|
||||||
port number. The <code>autoport</code> attribute is the
|
port to use. The <code>listen</code> attribute is an IP address
|
||||||
new preferred syntax for indicating autoallocation of
|
for the server to listen on. The <code>passwd</code> attribute
|
||||||
needed port numbers. The <code>listen</code> attribute is
|
provides a VNC password in clear text. The <code>keymap</code>
|
||||||
an IP address for the server to listen
|
attribute specifies the keymap to use. It is possible to set
|
||||||
on. The <code>passwd</code> attribute provides a SPICE
|
a limit on the validity of the password by giving an timestamp
|
||||||
password in clear text. The <code>keymap</code>
|
<code>passwdValidTo='2010-04-09T15:51:00'</code> assumed to be
|
||||||
attribute specifies the keymap to use. It is possible to
|
in UTC. The <code>connected</code> attribute allows control of
|
||||||
set a limit on the validity of the password be giving an
|
connected client during password changes. VNC accepts
|
||||||
timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
|
<code>keep</code> value only <span class="since">since 0.9.3</span>.
|
||||||
assumed to be in UTC. The <code>connected</code> attribute
|
|
||||||
allows control of connected client during password changes.
|
|
||||||
SPICE accepts <code>keep</code> to keep client connected,
|
|
||||||
<code>disconnect</code> to disconnect client and
|
|
||||||
<code>fail</code> to fail changing password.
|
|
||||||
<span class="since">Since 0.9.3</span>
|
|
||||||
NB, this may not be supported by all hypervisors.
|
NB, this may not be supported by all hypervisors.
|
||||||
<span class="since">"spice" since 0.8.6</span>.
|
|
||||||
The <code>defaultMode</code> attribute sets the default channel
|
|
||||||
security policy, valid values are <code>secure</code>,
|
|
||||||
<code>insecure</code> and the default <code>any</code>
|
|
||||||
(which is secure if possible, but falls back to insecure
|
|
||||||
rather than erroring out if no secure path is
|
|
||||||
available). <span class="since">"defaultMode" since
|
|
||||||
0.9.12</span>.
|
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
When SPICE has both a normal and TLS secured TCP port
|
The optional <code>sharePolicy</code> attribute specifies vnc
|
||||||
configured, it can be desirable to restrict what
|
server display sharing policy. <code>allow-exclusive</code> allows
|
||||||
channels can be run on each port. This is achieved by
|
clients to ask for exclusive access by dropping other connections.
|
||||||
adding one or more <channel> elements inside the
|
Connecting multiple clients in parallel requires all clients asking
|
||||||
main <graphics> element and setting the <code>mode</code>
|
for a shared session (vncviewer: -Shared switch). This is
|
||||||
attribute to either <code>secure</code> or <code>insecure</code>.
|
the default value. <code>force-shared</code> disables exclusive
|
||||||
Setting the mode attribute overrides the default value as set
|
client access, every connection has to specify -Shared switch for
|
||||||
by the <code>defaultMode</code> attribute. (Note that specifying
|
vncviewer. <code>ignore</code> welcomes every connection
|
||||||
|
unconditionally <span class="since">since 1.0.6</span>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Rather than using listen/port, QEMU supports a <code>socket</code>
|
||||||
|
attribute for listening on a unix domain socket path
|
||||||
|
<span class="since">Since 0.8.8</span>.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
For VNC WebSocket functionality, <code>websocket</code> attribute
|
||||||
|
may be used to specify port to listen on (with -1 meaning
|
||||||
|
auto-allocation and <code>autoport</code> having no effect due to
|
||||||
|
security reasons) <span class="since">Since 1.0.6</span>.
|
||||||
|
</p>
|
||||||
|
</dd>
|
||||||
|
<dt><code>"spice"</code> <span class="since">Since 0.8.6</span></dt>
|
||||||
|
<dd>
|
||||||
|
<p>
|
||||||
|
Starts a SPICE server. The <code>port</code> attribute specifies
|
||||||
|
the TCP port number (with -1 as legacy syntax indicating that it
|
||||||
|
should be auto-allocated), while <code>tlsPort</code> gives
|
||||||
|
an alternative secure port number. The <code>autoport</code>
|
||||||
|
attribute is the new preferred syntax for indicating
|
||||||
|
auto-allocation of needed port numbers. The <code>listen</code>
|
||||||
|
attribute is an IP address for the server to listen on.
|
||||||
|
The <code>passwd</code> attribute provides a SPICE password in
|
||||||
|
clear text. The <code>keymap</code> attribute specifies the keymap
|
||||||
|
to use. It is possible to set a limit on the validity of
|
||||||
|
the password by giving an timestamp
|
||||||
|
<code>passwdValidTo='2010-04-09T15:51:00'</code> assumed to be in
|
||||||
|
UTC.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <code>connected</code> attribute allows control of connected
|
||||||
|
client during password changes. SPICE accepts <code>keep</code> to
|
||||||
|
keep client connected, <code>disconnect</code> to disconnect client
|
||||||
|
and <code>fail</code> to fail changing password . NB, this may not
|
||||||
|
be supported by all hypervisors.
|
||||||
|
<span class="since">Since 0.9.3</span>
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The <code>defaultMode</code> attribute sets the default channel
|
||||||
|
security policy, valid values are <code>secure</code>,
|
||||||
|
<code>insecure</code> and the default <code>any</code> (which is
|
||||||
|
secure if possible, but falls back to insecure rather than erroring
|
||||||
|
out if no secure path is available).
|
||||||
|
<span class="since">Since 0.9.12</span>
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
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 <code><channel>
|
||||||
|
</code> elements inside the main <code><graphics></code>
|
||||||
|
element and setting the <code>mode</code> attribute to either
|
||||||
|
<code>secure</code> or <code>insecure</code>. Setting the mode
|
||||||
|
attribute overrides the default value as set by
|
||||||
|
the <code>defaultMode</code> attribute. (Note that specifying
|
||||||
<code>any</code> as mode discards the entry as the channel would
|
<code>any</code> as mode discards the entry as the channel would
|
||||||
inherit the default mode anyways)
|
inherit the default mode anyways.) Valid channel names include
|
||||||
Valid channel names
|
<code>main</code>, <code>display</code>, <code>inputs</code>,
|
||||||
include <code>main</code>, <code>display</code>,
|
<code>cursor</code>, <code>playback</code>, <code>record</code>
|
||||||
<code>inputs</code>, <code>cursor</code>,
|
|
||||||
<code>playback</code>, <code>record</code>
|
|
||||||
(all <span class="since"> since 0.8.6</span>);
|
(all <span class="since"> since 0.8.6</span>);
|
||||||
<code>smartcard</code> (<span class="since">since
|
<code>smartcard</code> (<span class="since">since 0.8.8</span>);
|
||||||
0.8.8</span>); and <code>usbredir</code>
|
and <code>usbredir</code> (<span class="since">since 0.9.12</span>).
|
||||||
(<span class="since">since 0.9.12</span>).
|
|
||||||
</p>
|
</p>
|
||||||
<pre>
|
<pre>
|
||||||
<graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
|
<graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
|
||||||
@ -5058,131 +5063,113 @@ qemu-kvm -net nic,model=? /dev/null
|
|||||||
<gl enable='yes'/>
|
<gl enable='yes'/>
|
||||||
</graphics></pre>
|
</graphics></pre>
|
||||||
<p>
|
<p>
|
||||||
Spice supports variable compression settings for audio,
|
Spice supports variable compression settings for audio, images and
|
||||||
images and streaming, <span class="since">since
|
streaming. These settings are accessible via the <code>compression
|
||||||
0.9.1</span>. These settings are accessible via
|
</code> attribute in all following elements: <code>image</code> to
|
||||||
the <code>compression</code> attribute in all following
|
set image compression (accepts <code>auto_glz</code>,
|
||||||
elements: <code>image</code> to set image compression
|
<code>auto_lz</code>, <code>quic</code>, <code>glz</code>,
|
||||||
(accepts <code>auto_glz</code>, <code>auto_lz</code>,
|
<code>lz</code>, <code>off</code>), <code>jpeg</code> for JPEG
|
||||||
<code>quic</code>, <code>glz</code>, <code>lz</code>,
|
compression for images over wan (accepts <code>auto</code>,
|
||||||
<code>off</code>), <code>jpeg</code> for JPEG
|
<code>never</code>, <code>always</code>), <code>zlib</code> for
|
||||||
compression for images over wan
|
configuring wan image compression (accepts <code>auto</code>,
|
||||||
(accepts <code>auto</code>, <code>never</code>,
|
<code>never</code>, <code>always</code>) and <code>playback</code>
|
||||||
<code>always</code>), <code>zlib</code> for configuring
|
for enabling audio stream compression (accepts <code>on</code> or
|
||||||
wan image compression (accepts <code>auto</code>,
|
<code>off</code>). <span class="since">Since 0.9.1</span>
|
||||||
<code>never</code>, <code>always</code>)
|
|
||||||
and <code>playback</code> for enabling audio stream
|
|
||||||
compression (accepts <code>on</code> or <code>off</code>).
|
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
Streaming mode is set by the <code>streaming</code>
|
Streaming mode is set by the <code>streaming</code> element,
|
||||||
element, settings its <code>mode</code> attribute to one
|
settings its <code>mode</code> attribute to one of
|
||||||
of <code>filter</code>, <code>all</code>
|
<code>filter</code>, <code>all</code> or <code>off</code>.
|
||||||
or <code>off</code>, <span class="since">since 0.9.2</span>.
|
<span class="since">Since 0.9.2</span>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
Copy & Paste functionality (via Spice agent) is set
|
Copy & Paste functionality (via Spice agent) is set by the
|
||||||
by the <code>clipboard</code> element. It is enabled by
|
<code>clipboard</code> element. It is enabled by default, and can
|
||||||
default, and can be disabled by setting
|
be disabled by setting the <code>copypaste</code> property to
|
||||||
the <code>copypaste</code> property
|
<code>no</code>. <span class="since">Since 0.9.3</span>
|
||||||
to <code>no</code>, <span class="since">since
|
|
||||||
0.9.3</span>.
|
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
Mouse mode is set by the <code>mouse</code> element,
|
Mouse mode is set by the <code>mouse</code> element, setting its
|
||||||
setting its <code>mode</code> attribute to one of
|
<code>mode</code> attribute to one of <code>server</code> or
|
||||||
<code>server</code> or <code>client</code> ,
|
<code>client</code>. If no mode is specified, the qemu default will
|
||||||
<span class="since">since 0.9.11</span>. If no mode is
|
be used (client mode). <span class="since">Since 0.9.11</span>
|
||||||
specified, the qemu default will be used (client mode).
|
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
File transfer functionality (via Spice agent) is set using the
|
File transfer functionality (via Spice agent) is set using the
|
||||||
<code>filetransfer</code> element.
|
<code>filetransfer</code> element. It is enabled by default, and
|
||||||
It is enabled by default, and can be disabled by setting the
|
can be disabled by setting the <code>enable</code> property to
|
||||||
<code>enable</code> property to <code>no</code> ,
|
<code>no</code>. <span class="since">Since 1.2.2</span>
|
||||||
since <span class="since">since 1.2.2</span>.
|
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
Spice may provide accelerated server-side rendering with
|
Spice may provide accelerated server-side rendering with OpenGL.
|
||||||
OpenGL. You can enable or disable OpenGL support explicitly with
|
You can enable or disable OpenGL support explicitly with
|
||||||
the <code>gl</code> element, by setting the
|
the <code>gl</code> element, by setting the <code>enable</code>
|
||||||
<code>enable</code> property. (QEMU
|
property. (QEMU only, <span class="since">since 1.3.2</span>).
|
||||||
only, <span class="since">since 1.3.2</span>).
|
|
||||||
</p>
|
</p>
|
||||||
</dd>
|
</dd>
|
||||||
<dt><code>"rdp"</code></dt>
|
<dt><code>"rdp"</code></dt>
|
||||||
<dd>
|
<dd>
|
||||||
Starts a RDP server. The <code>port</code> attribute
|
<p>
|
||||||
specifies the TCP port number (with -1 as legacy syntax
|
Starts a RDP server. The <code>port</code> attribute specifies the
|
||||||
indicating that it should be
|
TCP port number (with -1 as legacy syntax indicating that it should
|
||||||
auto-allocated). The <code>autoport</code> attribute is
|
be auto-allocated). The <code>autoport</code> attribute is the new
|
||||||
the new preferred syntax for indicating autoallocation of
|
preferred syntax for indicating auto-allocation of the TCP port to
|
||||||
the TCP port to use. The <code>replaceUser</code>
|
use. The <code>replaceUser</code> attribute is a boolean deciding
|
||||||
attribute is a boolean deciding whether multiple
|
whether multiple simultaneous connections to the VM are permitted.
|
||||||
simultaneous connections to the VM are permitted.
|
The <code>multiUser</code> attribute is a boolean deciding whether
|
||||||
The <code>multiUser</code> attribute is a boolean deciding
|
the existing connection must be dropped and a new connection must
|
||||||
whether the existing connection must be dropped and a new
|
be established by the VRDP server, when a new client connects in
|
||||||
connection must be established by the VRDP server, when a
|
single connection mode.
|
||||||
new client connects in single connection mode.
|
</p>
|
||||||
</dd>
|
</dd>
|
||||||
<dt><code>"desktop"</code></dt>
|
<dt><code>"desktop"</code></dt>
|
||||||
<dd>
|
<dd>
|
||||||
This value is reserved for VirtualBox domains for the
|
<p>
|
||||||
moment. It displays a window on the host desktop,
|
This value is reserved for VirtualBox domains for the moment. It
|
||||||
similarly to "sdl", but using the VirtualBox viewer. Just
|
displays a window on the host desktop, similarly to "sdl", but
|
||||||
like "sdl", it accepts the optional
|
using the VirtualBox viewer. Just like "sdl", it accepts
|
||||||
attributes <code>display</code>
|
the optional attributes <code>display</code> and
|
||||||
and <code>fullscreen</code>.
|
<code>fullscreen</code>.
|
||||||
|
</p>
|
||||||
</dd>
|
</dd>
|
||||||
</dl>
|
</dl>
|
||||||
</dd>
|
</dd>
|
||||||
</dl>
|
</dl>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Rather than putting the address information used to set up the
|
Graphics device uses a <code><listen></code> to set up where
|
||||||
listening socket for graphics types <code>vnc</code>
|
the device should listen for clients. It has a mandatory attribute
|
||||||
and <code>spice</code> in
|
<code>type</code> which specifies the listen type. Only <code>vnc</code>,
|
||||||
the <code><graphics></code> <code>listen</code> attribute,
|
<code>spice</code> and <code>rdp</code> supports <code><listen>
|
||||||
a separate subelement of <code><graphics></code>,
|
</code> element. <span class="since">Since 0.9.4</span>.
|
||||||
called <code><listen></code> can be specified (see the
|
Available types are:
|
||||||
examples above)<span class="since">since
|
|
||||||
0.9.4</span>. <code><listen></code> accepts the following
|
|
||||||
attributes:
|
|
||||||
</p>
|
</p>
|
||||||
<dl>
|
|
||||||
<dt><code>type</code></dt>
|
|
||||||
<dd>Set to either <code>address</code>
|
|
||||||
or <code>network</code>. This tells whether this listen
|
|
||||||
element is specifying the address to be used directly, or by
|
|
||||||
naming a network (which will then be used to determine an
|
|
||||||
appropriate address for listening).
|
|
||||||
</dd>
|
|
||||||
</dl>
|
|
||||||
<dl>
|
<dl>
|
||||||
<dt><code>address</code></dt>
|
<dt><code>address</code></dt>
|
||||||
<dd>if <code>type='address'</code>, the <code>address</code>
|
<dd>
|
||||||
attribute will contain either an IP address or hostname (which
|
<p>
|
||||||
will be resolved to an IP address via a DNS query) to listen
|
Tells a graphics device to use an address specified in the
|
||||||
on. In the "live" XML of a running domain, this attribute will
|
<code>address</code> attribute, which will contain either an IP address
|
||||||
be set to the IP address used for listening, even
|
or hostname (which will be resolved to an IP address via a DNS query)
|
||||||
if <code>type='network'</code>.
|
to listen on.
|
||||||
|
</p>
|
||||||
</dd>
|
</dd>
|
||||||
</dl>
|
|
||||||
<dl>
|
|
||||||
<dt><code>network</code></dt>
|
<dt><code>network</code></dt>
|
||||||
<dd>if <code>type='network'</code>, the <code>network</code>
|
<dd>
|
||||||
attribute will contain the name of a network in libvirt's list
|
<p>
|
||||||
of configured networks. The named network configuration will
|
This is used to specify an existing network in the <code>network</code>
|
||||||
be examined to determine an appropriate listen address. For
|
attribute from libvirt's list of configured networks. The named network
|
||||||
example, if the network has an IPv4 address in its
|
configuration will be examined to determine an appropriate listen
|
||||||
configuration (e.g. if it has a forward type
|
address and the address will be stored in live XML in <code>address
|
||||||
of <code>route</code>, <code>nat</code>, or no forward type
|
</code> attribute. For example, if the network has an IPv4 address in
|
||||||
(isolated)), the first IPv4 address listed in the network's
|
its configuration (e.g. if it has a forward type of <code>route</code>,
|
||||||
configuration will be used. If the network is describing a
|
<code>nat</code>, or no forward type (isolated)), the first IPv4
|
||||||
host bridge, the first IPv4 address associated with that
|
address listed in the network's configuration will be used.
|
||||||
bridge device will be used, and if the network is describing
|
If the network is describing a host bridge, the first IPv4 address
|
||||||
one of the 'direct' (macvtap) modes, the first IPv4 address of
|
associated with that bridge device will be used, and if the network is
|
||||||
the first forward dev will be used.
|
describing one of the 'direct' (macvtap) modes, the first IPv4 address
|
||||||
|
of the first forward dev will be used.
|
||||||
|
</p>
|
||||||
</dd>
|
</dd>
|
||||||
</dl>
|
</dl>
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user