[libvirt] [PATCH 02/18] docs: rewrite graphics XML documentation
Pavel Hrdina
phrdina at redhat.com
Mon Apr 4 13:20:19 UTC 2016
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 at redhat.com>
---
docs/formatdomain.html.in | 351 ++++++++++++++++++++++------------------------
1 file changed, 169 insertions(+), 182 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 957b839..c43c737 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -4933,108 +4933,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>.
+ <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 <channel> elements inside the
- main <graphics> 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
+ 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
- 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>
<graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
@@ -5048,131 +5053,113 @@ qemu-kvm -net nic,model=? /dev/null
<gl enable='yes'/>
</graphics></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 & 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 & 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><graphics></code> <code>listen</code> attribute,
- a separate subelement of <code><graphics></code>,
- called <code><listen></code> can be specified (see the
- examples above)<span class="since">since
- 0.9.4</span>. <code><listen></code> accepts the following
- attributes:
+ Graphics device uses a <code><listen></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><listen>
+ </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>
--
2.7.4
More information about the libvir-list
mailing list