openstack/openstack-manuals
Code Issues Proposed changes

Adds SPICE HTML5 doc, fixes console section

Browse Source 
partially fixes bug 1111126

WIP -  this does not build right now. Help welcome :)

SPICE HTML5 console support was added in Grizzly, this patch adds
a new section describing briefly why you would use SPICE over VNC,
and details its configuration options.

A new high-level section under interfaces we created for both to
live under.

The VNC console section has been reworked a little, to now include
the options from the table, which avoids a double-maintenance problem

patch2 adds a missing file

patch3 addresses comments from Daniel

patch4 adds a sentence about SPICE HTML5 arch, and removes hints that
       using both VNC and SPICE is possible :)

Patchset5 gets it building by further chunking which revealed a lack
of a <title> on one of the new sections.

Patchset6 just a rebase since Jenkins failed the prior patch.

Change-Id: I1437450dbfa943bfba92640c7d425d6a8ae40ac3
This commit is contained in:
Tom Fifield 2013-02-01 15:42:43 +11:00 committed by annegentle
parent df306467b8
commit 904b9618a7
9 changed files with 145 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/src/docbkx/openstack-compute-admin/bk-compute-adminguide.xml
View File

@ -44,6 +44,16 @@
managing, and understanding the software that runs OpenStack Compute. </para>
</abstract>
<revhistory>
<revision>
<date>2013-02-19</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Adds SPICE HTML5 information for remote access to server instances.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2012-11-09</date>
<revdescription>

1
doc/src/docbkx/openstack-compute-admin/compute-options-reference.xml
View File

@ -25,6 +25,7 @@
<xi:include href="tables/roles-auth-nova-conf.xml" />
<xi:include href="tables/nova-ec2-nova-conf.xml" />
<xi:include href="tables/vnc-guests-nova-conf.xml" />
<xi:include href="tables/spice-guests-nova-conf.xml" />
<xi:include href="tables/network-nova-conf.xml" />
<xi:include href="tables/live-migration-nova-conf.xml"/>
<xi:include href="tables/compute-nodes-nova-conf.xml" />

27
doc/src/docbkx/openstack-compute-admin/compute-spice-console.xml Normal file
View File

@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="spice-console">
<title>Spice Console</title>
<para>OpenStack Compute has long had support for VNC consoles to
guests. The VNC protocol is fairly limited, lacking support for
multiple monitors, bi-directional audio, reliable cut+paste, video
streaming and more. SPICE is a new protocol which aims to address
all the limitations in VNC, to provide good remote desktop
support.</para>
<para> SPICE support in OpenStack Compute shares a similar
architecture to the VNC implementation. The OpenStack Dashboard
uses a SPICE-HTML5 widget in its console tab, that communicates to
the <literal>nova-spicehtml5proxy</literal> service using
SPICE-over-websockets. The <literal>nova-spicehtml5proxy</literal>
service communicates directly with the hypervisor process using
SPICE.</para>
<para>Options for configuring SPICE as the console for OpenStack Compute can be found below.</para>
<xi:include href="tables/spice-guests-nova-conf.xml"/>
<!--<note><para>If you intend to support <link linkend="configuring-migrations">live migration</link>,
you cannot specify a specific IP address for <literal>server_listen</literal>,
because that IP address will not exist on the destination host.</para></note>-->
</section>

69
doc/src/docbkx/openstack-compute-admin/computevncconsole.xml → doc/src/docbkx/openstack-compute-admin/compute-vnc-console.xml
View File

@ -1,6 +1,7 @@
<?xml version="1.0"?>
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
version="5.0-extension RaxBook-1.0"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="getting-started-with-vnc-proxy">
<info>
<title>Overview of VNC Proxy</title>
@ -122,70 +123,22 @@
<prompt>$</prompt> <userinput>nova get-vnc-console <replaceable>[server_id]</replaceable> novnc</userinput>
</screen>
</section>
<section xml:id="important-nova-compute-options">
<info>
<title>Important nova-compute Options</title>
</info>
<para> To enable vncproxy in your cloud, in addition to running
one or both of the proxies and nova-consoleauth, you need to
configure the following options in
<filename>nova.conf</filename> on your compute hosts. </para>
<itemizedlist>
<listitem>
<para> <literal>[no]vnc_enabled</literal> - Defaults to enabled. If this option
is disabled your instances will launch without VNC
support. </para>
</listitem>
<listitem>
<para><literal>vncserver_listen</literal> - Defaults to <literal>127.0.0.1</literal>. This
is the address that vncservers will bind, and should be overridden in production
deployments as a private address. Applies to libvirt only. For multi-host libvirt
deployments this should be set to a host management IP on the same network as the
proxies.</para>
<note><para>If you intend to support <link linkend="configuring-migrations">live migration</link>,
<section xml:id="vnc-configuration-options">
<title>VNC Configuration Options</title>
<xi:include href="tables/vnc-guests-nova-conf.xml"/>
<note><para>If you intend to support <link linkend="configuring-migrations">live migration</link>,
you cannot specify a specific IP address for <literal>vncserver_listen</literal>,
because that IP address will not exist on the destination host. The result is that
live migration will fail and the following error will appear in the
<filename>libvirtd.log</filename> file in the destination
host:<programlisting>error: qemuMonitorIORead:513 : Unable to read from monitor: Connection reset by peer</programlisting>If
you wish to support live migration in your deployment, you must specify a value of
<literal>0.0.0.0</literal> for <literal>vncserver_listen</literal>. </para></note>
</listitem>
<listitem>
<para><literal>vncserver_proxyclient_address</literal> - Defaults to <literal>127.0.0.1</literal>.
because that IP address will not exist on the destination host.</para></note>
<note><para><literal>vncserver_proxyclient_address</literal> - Defaults to <literal>127.0.0.1</literal>.
This is the address of the compute host that nova will
instruct proxies to use when connecting to instance
vncservers. For all-in-one XenServer domU deployments
servers. For all-in-one XenServer domU deployments
this can be set to 169.254.0.1. For multi-host XenServer
domU deployments this can be set to a dom0 management ip
on the same network as the proxies. For multi-host libvirt
deployments this can be set to a host management IP on the
same network as the proxies. </para>
</listitem>
<listitem>
<para><literal>novncproxy_base_url</literal>=<replaceable>[base url for client connections]</replaceable>
- This is the public base URL to which clients will
connect. "?token=abc" will be added to this URL for the
purposes of auth. When using the system as described in
this document, an appropriate value is "<link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://$SERVICE_HOST:6080/vnc_auto.html"
>http://$SERVICE_HOST:6080/vnc_auto.html</link>" where
<replaceable>SERVICE_HOST</replaceable> is a public hostname. </para>
</listitem>
<listitem>
<para> <literal>xvpvncproxy_base_url</literal>=[base url for client
connections] - This is the public base URL to which
clients will connect. "?token=abc" will be added to this
URL for the purposes of auth. When using the system as
described in this document, an appropriate value is "<link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://$SERVICE_HOST:6081/console"
>http://$SERVICE_HOST:6081/console</link>" where
SERVICE_HOST is a public hostname. </para>
</listitem>
</itemizedlist>
same network as the proxies.</para></note>
</section>
<section xml:id="accessing-vnc-consoles-with-a-java-client">
<info>

4
doc/src/docbkx/openstack-compute-admin/computeconfigure.xml
View File

@ -1026,8 +1026,8 @@ ln -s $img_dir /images
sessions and object metadata</para>
</listitem>
<listitem>
<para>A chunk server (CSS) which store the datas as chunks and replicate them across the
chunkservers</para>
<para>A chunk server (CSS) which store the data as chunks
and replicate them across the chunkservers</para>
</listitem>
<listitem>
<para>A client, which talks with the MDS and interact with the CSS. MooseFS clients manage

35
doc/src/docbkx/openstack-compute-admin/computeinterfaces.xml
View File

@ -1,39 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_openstack-interfaces">
<title>OpenStack Interfaces</title>
<title>OpenStack Interfaces</title>
<para>OpenStack has components that provide a view of the
OpenStack installation such as a Django-built website that
serves as a dashboard and the ability to connect to running
instances using a VNC connection via a VNC Proxy.</para>
<section xml:id="about-the-dashboard">
<title>About the Dashboard</title>
<?dbhtml stop-chunking?>
<para>You can use a dashboard interface with an OpenStack
Compute installation with a web-based console provided by
the Openstack-Dashboard project. It provides web-based
interactions with the OpenStack Compute cloud controller
through the OpenStack APIs. For more information about the
Openstack-Dashboard project, please visit: <link
xlink:href="https://github.com/openstack/horizon/"
>https://github.com/openstack/horizon/</link>. These
instructions are for an example deployment configured with
an Apache web server. </para>
<xi:include href="../openstack-install/dashboard-system-reqs.xml"/>
<xi:include href="../openstack-install/dashboard-install.xml"/>
<xi:include href="../openstack-install/dashboard-configure.xml"/>
<xi:include href="../openstack-install/dashboard-verify.xml"/>
<xi:include href="../common/dashboard_customizing.xml" />
<xi:include href="../common/dashboardlaunchinginstances.xml"/>
</section>
<xi:include href="computevncconsole.xml"/>
<xi:include href="../openstack-install/about-dashboard.xml"/>
<xi:include href="remote-console-access.xml"/>
</chapter>

17
doc/src/docbkx/openstack-compute-admin/remote-console-access.xml Normal file
View File

@ -0,0 +1,17 @@
<section
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="remote-console-access">
<title>Remote Console Access</title>
<!--<?dbhtml stop-chunking?>-->
<para>OpenStack has two main methods for providing a remote
console or remote desktop access to guest Virtual
Machines. They are VNC, and SPICE HTML5 and can be used
either through the OpenStack dashboard and the command
line. Best practice is to select one or the other to
run.</para>
<xi:include href="compute-vnc-console.xml"/>
<xi:include href="compute-spice-console.xml"/>
</section>

45
doc/src/docbkx/openstack-compute-admin/tables/spice-guests-nova-conf.xml Normal file
View File

@ -0,0 +1,45 @@
<?xml version="1.0" encoding="UTF-8"?>
<para xmlns= "http://docbook.org/ns/docbook" version= "5.0">
<table rules= "all">
<caption>Description of nova.conf [spice] section configuration options
for SPICE HTML5 access to guest instances</caption>
<col width= "50%"/>
<col width= "50%"/>
<thead>
<tr>
<td><para>Configuration option=Default value</para></td>
<td><para>(Type) Description</para></td>
</tr>
</thead>
<tbody>
<tr>
<td><para>
html5proxy_base_url=http://127.0.0.1:6080/spice_auto.html </para></td>
<td><para> (StrOpt) location of spice html5 console proxy, in the
form "http://127.0.0.1:6080/spice_auto.html" </para></td>
</tr>
<tr>
<td><para> enabled=false </para></td>
<td><para> (BoolOpt) enable spice related features </para></td>
</tr>
<tr>
<td><para> agent_enabled=true </para></td>
<td><para> (BoolOpt) enable spice guest agent support </para></td>
</tr>
<tr>
<td><para> keymap=en-us </para></td>
<td><para> (StrOpt) keymap for spice</para></td>
</tr>
<tr>
<td><para> server_listen=127.0.0.1 </para></td>
<td><para> (StrOpt) IP address on which instance
spice servers should listen </para></td>
</tr>
<tr>
<td><para> server_proxyclient_address=127.0.0.1 </para></td>
<td><para> (StrOpt) the address to which proxy clients (like
nova-html5proxy) should connect </para></td>
</tr>
</tbody>
</table>
</para>

27
doc/src/docbkx/openstack-install/about-dashboard.xml Normal file
View File

@ -0,0 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="about-the-dashboard">
<title>About the Dashboard</title>
<!--<?dbhtml stop-chunking?>-->
<para>You can use a dashboard interface with an OpenStack
Compute installation with a web-based console provided by
the Openstack-Dashboard project. It provides web-based
interactions with the OpenStack Compute cloud controller
through the OpenStack APIs. For more information about the
Openstack-Dashboard project, please visit: <link
xlink:href="https://github.com/openstack/horizon/"
>https://github.com/openstack/horizon/</link>. These
instructions are for an example deployment configured with
an Apache web server. </para>
<xi:include href="../openstack-install/dashboard-system-reqs.xml"/>
<xi:include href="../openstack-install/dashboard-install.xml"/>
<xi:include href="../openstack-install/dashboard-configure.xml"/>
<xi:include href="../openstack-install/dashboard-verify.xml"/>
<xi:include href="../common/dashboard_customizing.xml"/>
<xi:include href="../common/dashboardlaunchinginstances.xml"/>
</section>