提交 f037a955 编写于 作者: P Pavel Hrdina

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: NPavel Hrdina <phrdina@redhat.com>
上级 71ea1085
......@@ -4943,108 +4943,113 @@ qemu-kvm -net nic,model=? /dev/null
<dl>
<dt><code>graphics</code></dt>
<dd>The <code>graphics</code> element has a mandatory <code>type</code>
attribute which takes the value "sdl", "vnc", "spice", "rdp" or
"desktop":
<dd>
<p>
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>
<dt><code>"sdl"</code></dt>
<dd>
This displays a window on the host desktop, it can take 3
optional arguments: a <code>display</code> attribute for
the display to use, an <code>xauth</code> attribute for
the authentication identifier, and an
optional <code>fullscreen</code> attribute accepting
values 'yes' or 'no'.
<p>
This displays a window on the host desktop, it can take 3 optional
arguments: a <code>display</code> attribute for the display to use,
an <code>xauth</code> attribute for the authentication identifier,
and an optional <code>fullscreen</code> attribute accepting values
<code>yes</code> or <code>no</code>.
</p>
</dd>
<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>
<p>
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 auto-allocation 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 by 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.
</p>
<p>
The optional <code>sharePolicy</code> attribute specifies vnc
server display sharing policy. <code>allow-exclusive</code> 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. <code>force-shared</code> disables exclusive
client access, every connection has to specify -Shared switch for
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></dt>
<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 autoallocation 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 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.
SPICE accepts <code>keep</code> to keep client connected,
<code>disconnect</code> to disconnect client and
<code>fail</code> to fail changing password.
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>
NB, this may not be supported by all hypervisors.
<span class="since">"spice" since 0.8.6</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">"defaultMode" 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 &lt;channel&gt; elements inside the
main &lt;graphics&gt; 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>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>&lt;channel&gt;
</code> elements inside the main <code>&lt;graphics&gt;</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
inherit the default mode anyways)
Valid channel names
include <code>main</code>, <code>display</code>,
<code>inputs</code>, <code>cursor</code>,
<code>playback</code>, <code>record</code>
inherit the default mode anyways.) Valid channel names include
<code>main</code>, <code>display</code>, <code>inputs</code>,
<code>cursor</code>, <code>playback</code>, <code>record</code>
(all <span class="since"> since 0.8.6</span>);
<code>smartcard</code> (<span class="since">since
0.8.8</span>); and <code>usbredir</code>
(<span class="since">since 0.9.12</span>).
<code>smartcard</code> (<span class="since">since 0.8.8</span>);
and <code>usbredir</code> (<span class="since">since 0.9.12</span>).
</p>
<pre>
&lt;graphics type='spice' port='-1' tlsPort='-1' autoport='yes'&gt;
......@@ -5058,131 +5063,113 @@ qemu-kvm -net nic,model=? /dev/null
&lt;gl enable='yes'/&gt;
&lt;/graphics&gt;</pre>
<p>
Spice supports variable compression settings for audio,
images and streaming, <span class="since">since
0.9.1</span>. These settings are accessible via
the <code>compression</code> attribute in all following
elements: <code>image</code> to set image compression
(accepts <code>auto_glz</code>, <code>auto_lz</code>,
<code>quic</code>, <code>glz</code>, <code>lz</code>,
<code>off</code>), <code>jpeg</code> for JPEG
compression for images over wan
(accepts <code>auto</code>, <code>never</code>,
<code>always</code>), <code>zlib</code> for configuring
wan image compression (accepts <code>auto</code>,
<code>never</code>, <code>always</code>)
and <code>playback</code> for enabling audio stream
compression (accepts <code>on</code> or <code>off</code>).
Spice supports variable compression settings for audio, images and
streaming. These settings are accessible via the <code>compression
</code> attribute in all following elements: <code>image</code> to
set image compression (accepts <code>auto_glz</code>,
<code>auto_lz</code>, <code>quic</code>, <code>glz</code>,
<code>lz</code>, <code>off</code>), <code>jpeg</code> for JPEG
compression for images over wan (accepts <code>auto</code>,
<code>never</code>, <code>always</code>), <code>zlib</code> for
configuring wan image compression (accepts <code>auto</code>,
<code>never</code>, <code>always</code>) and <code>playback</code>
for enabling audio stream compression (accepts <code>on</code> or
<code>off</code>). <span class="since">Since 0.9.1</span>
</p>
<p>
Streaming mode is set by the <code>streaming</code>
element, settings its <code>mode</code> attribute to one
of <code>filter</code>, <code>all</code>
or <code>off</code>, <span class="since">since 0.9.2</span>.
Streaming mode is set by the <code>streaming</code> element,
settings its <code>mode</code> attribute to one of
<code>filter</code>, <code>all</code> or <code>off</code>.
<span class="since">Since 0.9.2</span>
</p>
<p>
Copy &amp; Paste functionality (via Spice agent) is set
by the <code>clipboard</code> element. It is enabled by
default, and can be disabled by setting
the <code>copypaste</code> property
to <code>no</code>, <span class="since">since
0.9.3</span>.
Copy &amp; Paste functionality (via Spice agent) is set by the
<code>clipboard</code> element. It is enabled by default, and can
be disabled by setting the <code>copypaste</code> property to
<code>no</code>. <span class="since">Since 0.9.3</span>
</p>
<p>
Mouse mode is set by the <code>mouse</code> element,
setting its <code>mode</code> attribute to one of
<code>server</code> or <code>client</code> ,
<span class="since">since 0.9.11</span>. If no mode is
specified, the qemu default will be used (client mode).
Mouse mode is set by the <code>mouse</code> element, setting its
<code>mode</code> attribute to one of <code>server</code> or
<code>client</code>. If no mode is specified, the qemu default will
be used (client mode). <span class="since">Since 0.9.11</span>
</p>
<p>
File transfer functionality (via Spice agent) is set using the
<code>filetransfer</code> element.
It is enabled by default, and can be disabled by setting the
<code>enable</code> property to <code>no</code> ,
since <span class="since">since 1.2.2</span>.
<code>filetransfer</code> element. It is enabled by default, and
can be disabled by setting the <code>enable</code> property to
<code>no</code>. <span class="since">Since 1.2.2</span>
</p>
<p>
Spice may provide accelerated server-side rendering with
OpenGL. You can enable or disable OpenGL support explicitly with
the <code>gl</code> element, by setting the
<code>enable</code> property. (QEMU
only, <span class="since">since 1.3.2</span>).
Spice may provide accelerated server-side rendering with OpenGL.
You can enable or disable OpenGL support explicitly with
the <code>gl</code> element, by setting the <code>enable</code>
property. (QEMU only, <span class="since">since 1.3.2</span>).
</p>
</dd>
<dt><code>"rdp"</code></dt>
<dd>
Starts a RDP 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>replaceUser</code>
attribute is a boolean deciding whether multiple
simultaneous connections to the VM are permitted.
The <code>multiUser</code> 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.
<p>
Starts a RDP 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 auto-allocation of the TCP port to
use. The <code>replaceUser</code> attribute is a boolean deciding
whether multiple simultaneous connections to the VM are permitted.
The <code>multiUser</code> 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.
</p>
</dd>
<dt><code>"desktop"</code></dt>
<dd>
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 <code>display</code>
and <code>fullscreen</code>.
<p>
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 <code>display</code> and
<code>fullscreen</code>.
</p>
</dd>
</dl>
</dd>
</dl>
<p>
Rather than putting the address information used to set up the
listening socket for graphics types <code>vnc</code>
and <code>spice</code> in
the <code>&lt;graphics&gt;</code> <code>listen</code> attribute,
a separate subelement of <code>&lt;graphics&gt;</code>,
called <code>&lt;listen&gt;</code> can be specified (see the
examples above)<span class="since">since
0.9.4</span>. <code>&lt;listen&gt;</code> accepts the following
attributes:
Graphics device uses a <code>&lt;listen&gt;</code> to set up where
the device should listen for clients. It has a mandatory attribute
<code>type</code> which specifies the listen type. Only <code>vnc</code>,
<code>spice</code> and <code>rdp</code> supports <code>&lt;listen&gt;
</code> element. <span class="since">Since 0.9.4</span>.
Available types are:
</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>
<dt><code>address</code></dt>
<dd>if <code>type='address'</code>, the <code>address</code>
attribute will contain either an IP address or hostname (which
will be resolved to an IP address via a DNS query) to listen
on. In the "live" XML of a running domain, this attribute will
be set to the IP address used for listening, even
if <code>type='network'</code>.
<dd>
<p>
Tells a graphics device to use an address specified in the
<code>address</code> 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.
</p>
</dd>
</dl>
<dl>
<dt><code>network</code></dt>
<dd>if <code>type='network'</code>, the <code>network</code>
attribute will contain the name of a network in libvirt's list
of configured networks. The named network configuration will
be examined to determine an appropriate listen address. For
example, if the network has an IPv4 address in its
configuration (e.g. if it has a forward type
of <code>route</code>, <code>nat</code>, 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.
<dd>
<p>
This is used to specify an existing network in the <code>network</code>
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 <code>address
</code> attribute. For example, if the network has an IPv4 address in
its configuration (e.g. if it has a forward type of <code>route</code>,
<code>nat</code>, 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.
</p>
</dd>
</dl>
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册