300 lines
14 KiB
XML
300 lines
14 KiB
XML
<?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="getting-started-with-vnc-proxy">
|
|
<title>VNC console proxy</title>
|
|
<para>The VNC proxy is an OpenStack component that enables compute
|
|
service users to access their instances through VNC
|
|
clients.</para>
|
|
<para>The VNC console connection works as follows:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>A user connects to the API and gets an
|
|
<literal>access_url</literal> such as,
|
|
<literal>http://<replaceable>ip:port</replaceable>/?token=xyz</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The user pastes the URL in a browser or uses it as a
|
|
client parameter.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The browser or client connects to the proxy.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The proxy talks to <systemitem class="service"
|
|
>nova-consoleauth</systemitem> to authorize the token for
|
|
the user, and maps the token to the
|
|
<emphasis>private</emphasis> host and port of the VNC server
|
|
for an instance.</para>
|
|
<para>The compute host specifies the address that the proxy
|
|
should use to connect through the
|
|
<filename>nova.conf</filename> file option,
|
|
<option>vncserver_proxyclient_address</option>. In this way,
|
|
the VNC proxy works as a bridge between the public network and
|
|
private host network.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The proxy initiates the connection to VNC server and
|
|
continues to proxy until the session ends.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>The proxy also tunnels the VNC protocol over WebSockets so that the
|
|
<systemitem>noVNC</systemitem> client can talk to VNC servers. In general, the VNC
|
|
proxy:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Bridges between the public network where the clients live and the private network where
|
|
VNC servers live.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Mediates token authentication.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Transparently deals with hypervisor-specific connection
|
|
details to provide a uniform client experience.</para>
|
|
<figure xml:id="novnc-process">
|
|
<title>noVNC process</title>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata
|
|
fileref="../common/figures/novnc/SCH_5009_V00_NUAC-VNC_OpenStack.png"
|
|
format="PNG" width="5in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</figure>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<section xml:id="about-nova-consoleauth">
|
|
<info>
|
|
<title>About nova-consoleauth</title>
|
|
</info>
|
|
<para>Both client proxies leverage a shared service to manage
|
|
token authentication called <systemitem class="service"
|
|
>nova-consoleauth</systemitem>. This service must be running
|
|
for either proxy to work. Many proxies of either type can be run
|
|
against a single <systemitem class="service"
|
|
>nova-consoleauth</systemitem> service in a cluster
|
|
configuration.</para>
|
|
<para>Do not confuse the <systemitem class="service"
|
|
>nova-consoleauth</systemitem> shared service with
|
|
<literal>nova-console</literal>, which is a XenAPI-specific
|
|
service that most recent VNC proxy architectures do not
|
|
use.</para>
|
|
</section>
|
|
<section xml:id="typical-deployment">
|
|
<title>Typical deployment</title>
|
|
<para>A typical deployment has the following components:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A <systemitem class="service"
|
|
>nova-consoleauth</systemitem> process. Typically runs on
|
|
the controller host.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>One or more <systemitem class="service"
|
|
>nova-novncproxy</systemitem> services. Supports
|
|
browser-based noVNC clients. For simple deployments, this
|
|
service typically runs on the same machine as <systemitem
|
|
class="service">nova-api</systemitem> because it operates
|
|
as a proxy between the public network and the private
|
|
compute host network.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>One or more <literal>nova-xvpvncproxy</literal>
|
|
services. Supports the special Java client discussed here.
|
|
For simple deployments, this service typically runs on the
|
|
same machine as <systemitem class="service"
|
|
>nova-api</systemitem> because it acts as a proxy between
|
|
the public network and the private compute host
|
|
network.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>One or more compute hosts. These compute hosts must have
|
|
correctly configured options, as follows.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="vnc-configuration-options">
|
|
<title>VNC configuration options</title>
|
|
<para>To customize the VNC console, use the following configuration options in your <filename>nova.conf</filename> file:</para>
|
|
<xi:include href="../common/tables/nova-vnc.xml"/>
|
|
<note>
|
|
<para>To support <link
|
|
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_configuring-compute-migrations.html"
|
|
>live migration</link>, you cannot specify a specific IP
|
|
address for <literal>vncserver_listen</literal>, because that
|
|
IP address does not exist on the destination host.</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The <literal>vncserver_proxyclient_address</literal> defaults to
|
|
<literal>127.0.0.1</literal>, which is the address of the compute host that
|
|
Compute instructs proxies to use when connecting to instance servers.
|
|
</para>
|
|
</listitem>
|
|
<listitem><para>For all-in-one XenServer domU deployments, set this to 169.254.0.1.</para></listitem>
|
|
<listitem><para>For multi-host XenServer domU deployments, set to a dom0 management IP on the
|
|
same network as the proxies.</para></listitem>
|
|
<listitem><para>For multi-host libvirt deployments, set to a host management IP on the same
|
|
network as the proxies.</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="nova-vncproxy-replaced-with-nova-novncproxy">
|
|
<info>
|
|
<title>nova-novncproxy (noVNC)</title>
|
|
</info>
|
|
<para>You must install the <package>noVNC</package> package, which contains the <systemitem
|
|
class="service">nova-novncproxy</systemitem> service. As root, run the following
|
|
command:</para>
|
|
<programlisting language="bash" role="gutter: false"><prompt>#</prompt> <userinput>apt-get install nova-novncproxy</userinput></programlisting>
|
|
<para>The service starts automatically on installation.</para>
|
|
<para>To restart the service, run:</para>
|
|
<programlisting language="bash" role="gutter: false"><prompt>#</prompt> <userinput>service nova-novncproxy restart</userinput></programlisting>
|
|
<para>The configuration option parameter should point to your
|
|
<filename>nova.conf</filename> file, which includes the
|
|
message queue server address and credentials.</para>
|
|
<para>By default, <systemitem class="service"
|
|
>nova-novncproxy</systemitem> binds on
|
|
<literal>0.0.0.0:6080</literal>.</para>
|
|
<para>To connect the service to your Compute deployment, add the following configuration options
|
|
to your <filename>nova.conf</filename> file:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<literal>vncserver_listen</literal>=<replaceable>0.0.0.0</replaceable>
|
|
</para>
|
|
<para>Specifies the address on which the VNC service should
|
|
bind. Make sure it is assigned one of the compute node
|
|
interfaces. This address is the one used by your domain
|
|
file.</para>
|
|
<programlisting language="bash" role="gutter: false"> <graphics type="vnc" autoport="yes" keymap="en-us" listen="0.0.0.0"/></programlisting>
|
|
<note>
|
|
<para>To use live migration, use the
|
|
<replaceable>0.0.0.0</replaceable> address.</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>vncserver_proxyclient_address</literal>=<replaceable>127.0.0.1</replaceable>
|
|
</para>
|
|
<para>The address of the compute host that Compute instructs proxies to use when connecting
|
|
to instance <literal>vncservers</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="faq-about-vnc">
|
|
<info>
|
|
<title>Frequently asked questions about VNC access to virtual
|
|
machines</title>
|
|
</info>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Q: What is the difference between
|
|
<literal>nova-xvpvncproxy</literal> and <systemitem
|
|
class="service">nova-novncproxy</systemitem>?</emphasis>
|
|
</para>
|
|
<para>A: <literal>nova-xvpvncproxy</literal>, which ships with OpenStack Compute, is a proxy
|
|
that supports a simple Java client. <systemitem class="service"
|
|
>nova-novncproxy</systemitem> uses noVNC to provide VNC support through a web
|
|
browser.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Q: I want VNC support in the OpenStack dashboard. What services
|
|
do I need? </emphasis></para>
|
|
<para>A: You need <systemitem class="service"
|
|
>nova-novncproxy</systemitem>, <systemitem class="service"
|
|
>nova-consoleauth</systemitem>, and correctly configured
|
|
compute hosts.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Q: When I use <command>nova get-vnc-console</command> or click
|
|
on the VNC tab of the OpenStack dashboard, it hangs. Why? </emphasis></para>
|
|
<para>A: Make sure you are running <systemitem class="service"
|
|
>nova-consoleauth</systemitem> (in addition to <systemitem
|
|
class="service">nova-novncproxy</systemitem>). The proxies
|
|
rely on <systemitem class="service"
|
|
>nova-consoleauth</systemitem> to validate tokens, and
|
|
waits for a reply from them until a timeout is reached.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Q: My VNC proxy worked fine during
|
|
my all-in-one test, but now it doesn't work on multi host.
|
|
Why? </emphasis></para>
|
|
<para>A: The default options work for an all-in-one install,
|
|
but changes must be made on your compute hosts once you
|
|
start to build a cluster. As an example, suppose you have
|
|
two servers:</para>
|
|
<programlisting language="bash" role="gutter: false">PROXYSERVER (public_ip=172.24.1.1, management_ip=192.168.1.1)
|
|
COMPUTESERVER (management_ip=192.168.1.2)</programlisting>
|
|
<para>Your <systemitem class="service"
|
|
>nova-compute</systemitem> configuration file must set the
|
|
following values:</para>
|
|
<programlisting language="bash" role="gutter: false"># These flags help construct a connection data structure
|
|
vncserver_proxyclient_address=192.168.1.2
|
|
novncproxy_base_url=http://172.24.1.1:6080/vnc_auto.html
|
|
xvpvncproxy_base_url=http://172.24.1.1:6081/console
|
|
|
|
# This is the address where the underlying vncserver (not the proxy)
|
|
# will listen for connections.
|
|
vncserver_listen=192.168.1.2</programlisting>
|
|
<note>
|
|
<para><literal>novncproxy_base_url</literal> and
|
|
<literal>xvpvncproxy_base_url</literal> use a public IP;
|
|
this is the URL that is ultimately returned to clients,
|
|
which generally do not have access to your private
|
|
network. Your PROXYSERVER must be able to reach
|
|
<literal>vncserver_proxyclient_address</literal>,
|
|
because that is the address over which the VNC connection
|
|
is proxied.</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="bold">Q: My noVNC does not work with recent
|
|
versions of web browsers. Why?</emphasis>
|
|
</para>
|
|
<para>A: Make sure you have installed
|
|
<literal>python-numpy</literal>, which is required to
|
|
support a newer version of the WebSocket protocol
|
|
(HyBi-07+).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="bold">Q: How do I adjust the dimensions of
|
|
the VNC window image in the OpenStack
|
|
dashboard?</emphasis></para>
|
|
<para>A: These values are hard-coded in a Django HTML
|
|
template. To alter them, edit the
|
|
<filename>_detail_vnc.html</filename> template file. The
|
|
location of this file varies based on Linux distribution. On
|
|
Ubuntu 14.04, the file is at
|
|
<filename>/usr/share/pyshared/horizon/dashboards/nova/instances/templates/instances/_detail_vnc.html</filename>.</para>
|
|
<para>Modify the <option>width</option> and
|
|
<option>height</option> options, as follows:</para>
|
|
<programlisting language="bash" role="gutter: false"><iframe src="{{ vnc_url }}" width="720" height="430"></iframe></programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis role="bold">Q: My noVNC connections failed with
|
|
ValidationError: Origin header protocol does not match.
|
|
Why?</emphasis>
|
|
</para>
|
|
<para>A: Make sure the <literal>base_url</literal> match your TLS
|
|
setting. If you are using https console connections, make sure
|
|
that the value of <literal>novncproxy_base_url</literal> is set
|
|
explicitly where the <systemitem class="service">nova-novncproxy</systemitem>
|
|
service is running.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|