[cloudstack-docs.git] / en-US / console-proxy.xml
1 <?xml version='1.0' encoding='utf-8' ?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3 <!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
5 ]>
6 <!-- Licensed to the Apache Software Foundation (ASF) under one
7 or more contributor license agreements. See the NOTICE file
8 distributed with this work for additional information
9 regarding copyright ownership. The ASF licenses this file
10 to you under the Apache License, Version 2.0 (the
11 "License"); you may not use this file except in compliance
12 with the License. You may obtain a copy of the License at
13 http://www.apache.org/licenses/LICENSE-2.0
14 Unless required by applicable law or agreed to in writing,
15 software distributed under the License is distributed on an
17 KIND, either express or implied. See the License for the
18 specific language governing permissions and limitations
19 under the License.
20 -->
21 <section id="console-proxy">
22 <title>Console Proxy</title>
23 <para>The Console Proxy is a type of System Virtual Machine that has a role in presenting a
24 console view via the web UI. It connects the user’s browser to the VNC port made available via
25 the hypervisor for the console of the guest. Both the administrator and end user web UIs offer a
26 console connection.</para>
27 <para>Clicking a console icon brings up a new window. The AJAX code downloaded into that window
28 refers to the public IP address of a console proxy VM. There is exactly one public IP address
29 allocated per console proxy VM. The AJAX application connects to this IP. The console proxy then
30 proxies the connection to the VNC port for the requested VM on the Host hosting the
31 guest.</para>
32 <note>
33 <para>The hypervisors will have many ports assigned to VNC usage so that multiple VNC sessions
34 can occur simultaneously.</para>
35 </note>
36 <para>There is never any traffic to the guest virtual IP, and there is no need to enable VNC
37 within the guest.</para>
38 <para>The console proxy VM will periodically report its active session count to the Management
39 Server. The default reporting interval is five seconds. This can be changed through standard
40 Management Server configuration with the parameter consoleproxy.loadscan.interval.</para>
41 <para>Assignment of guest VM to console proxy is determined by first determining if the guest VM
42 has a previous session associated with a console proxy. If it does, the Management Server will
43 assign the guest VM to the target Console Proxy VM regardless of the load on the proxy VM.
44 Failing that, the first available running Console Proxy VM that has the capacity to handle new
45 sessions is used.</para>
46 <para>Console proxies can be restarted by administrators but this will interrupt existing console
47 sessions for users.</para>
48 <section id="use-cert">
49 <title>Using a SSL Certificate for the Console Proxy</title>
50 <para>The console viewing functionality uses a dynamic DNS service under the domain name
51 realhostip.com to assist in providing SSL security to console sessions. The console proxy is
52 assigned a public IP address. In order to avoid browser warnings for mismatched SSL
53 certificates, the URL for the new console window is set to the form of
54 https://aaa-bbb-ccc-ddd.realhostip.com. You will see this URL during console session creation.
55 &PRODUCT; includes the realhostip.com SSL certificate in the console proxy VM. Of course,
56 &PRODUCT; cannot know about the DNS A records for our customers' public IPs prior to shipping
57 the software. &PRODUCT; therefore runs a dynamic DNS server that is authoritative for the
58 realhostip.com domain. It maps the aaa-bbb-ccc-ddd part of the DNS name to the IP address
59 aaa.bbb.ccc.ddd on lookups. This allows the browser to correctly connect to the console
60 proxy's public IP, where it then expects and receives a SSL certificate for realhostip.com,
61 and SSL is set up without browser warnings.</para>
62 </section>
63 <section id="change-console-proxy-ssl-certificate-domain">
64 <title>Changing the Console Proxy SSL Certificate and Domain</title>
65 <para>If the administrator prefers, it is possible for the URL of the customer's console session
66 to show a domain other than realhostip.com. The administrator can customize the displayed
67 domain by selecting a different domain and uploading a new SSL certificate and private key.
68 The domain must run a DNS service that is capable of resolving queries for addresses of the
69 form aaa-bbb-ccc-ddd.your.domain to an IPv4 IP address in the form aaa.bbb.ccc.ddd, for
70 example, To change the console proxy domain, SSL certificate, and private
71 key:</para>
72 <orderedlist>
73 <listitem>
74 <para>Set up dynamic name resolution or populate all possible DNS names in your public IP
75 range into your existing DNS server with the format aaa-bbb-ccc-ddd.company.com ->
76 aaa.bbb.ccc.ddd.</para>
77 </listitem>
78 <listitem>
79 <para>Generate the private key and certificate signing request (CSR). When you are using
80 openssl to generate private/public key pairs and CSRs, for the private key that you are
81 going to paste into the &PRODUCT; UI, be sure to convert it into PKCS#8 format.</para>
82 <orderedlist numeration="loweralpha">
83 <listitem>
84 <para>Generate a new 2048-bit private key</para>
85 <programlisting>openssl genrsa -des3 -out yourprivate.key 2048</programlisting>
86 </listitem>
87 <listitem>
88 <para>Generate a new certificate CSR</para>
89 <programlisting>openssl req -new -key yourprivate.key -out yourcertificate.csr</programlisting>
90 </listitem>
91 <listitem>
92 <para>Head to the website of your favorite trusted Certificate Authority, purchase an
93 SSL certificate, and submit the CSR. You should receive a valid certificate in
94 return</para>
95 </listitem>
96 <listitem>
97 <para>Convert your private key format into PKCS#8 encrypted format.</para>
98 <programlisting>openssl pkcs8 -topk8 -in yourprivate.key -out yourprivate.pkcs8.encrypted.key</programlisting>
99 </listitem>
100 <listitem>
101 <para>Convert your PKCS#8 encrypted private key into the PKCS#8 format that is compliant
102 with &PRODUCT;</para>
103 <programlisting>openssl pkcs8 -in yourprivate.pkcs8.encrypted.key -out yourprivate.pkcs8.key</programlisting>
104 </listitem>
105 </orderedlist>
106 </listitem>
107 <listitem>
108 <para>In the Update SSL Certificate screen of the &PRODUCT; UI, paste the following:</para>
109 <itemizedlist>
110 <listitem>
111 <para>The certificate you've just generated.</para>
112 </listitem>
113 <listitem>
114 <para>The private key you've just generated.</para>
115 </listitem>
116 <listitem>
117 <para>The desired new domain name; for example, company.com</para>
118 </listitem>
119 </itemizedlist>
120 <mediaobject>
121 <imageobject>
122 <imagedata fileref="./images/update-ssl.png"/>
123 </imageobject>
124 <textobject>
125 <phrase>updatessl.png: Updating Console Proxy SSL Certificate</phrase>
126 </textobject>
127 </mediaobject>
128 </listitem>
129 <listitem>
130 <para>The desired new domain name; for example, company.com</para>
131 <para>This stops all currently running console proxy VMs, then restarts them with the new
132 certificate and key. Users might notice a brief interruption in console
133 availability.</para>
134 </listitem>
135 </orderedlist>
136 <para>The Management Server generates URLs of the form "aaa-bbb-ccc-ddd.company.com" after this
137 change is made. The new console requests will be served with the new DNS domain name,
138 certificate, and key.</para>
139 </section>
140 </section>