realip host changes and cpu sockets changes
[cloudstack-docs.git] / en-US / realip-changes.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">
4 %BOOK_ENTITIES;
5 ]>
6
7 <!-- Licensed to the Apache Software Foundation (ASF) under one
8 or more contributor license agreements. See the NOTICE file
9 distributed with this work for additional information
10 regarding copyright ownership. The ASF licenses this file
11 to you under the Apache License, Version 2.0 (the
12 "License"); you may not use this file except in compliance
13 with the License. You may obtain a copy of the License at
14
15 http://www.apache.org/licenses/LICENSE-2.0
16
17 Unless required by applicable law or agreed to in writing,
18 software distributed under the License is distributed on an
19 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20 KIND, either express or implied. See the License for the
21 specific language governing permissions and limitations
22 under the License.
23 -->
24 <section id="realip-changes">
25 <title>Secure Connections for &PRODUCT;System VMs</title>
26 <para>&PRODUCT; System VMs, such as console proxy and Secondary storage VMs, use SSL certificates
27 to host HTTPS connections. Because each &PRODUCT; environment is unique, System VMs in each
28 deployment varies and each instance will have its own set of IP addresses. To use one SSL
29 certificate across all the instances among different deployments, &PRODUCT; provides a global
30 parameter based mechanism. To achieve that you need the following:</para>
31 <itemizedlist>
32 <listitem>
33 <para>A software that runs a wildcard DNS service.</para>
34 </listitem>
35 <listitem>
36 <para>A wildcard certificate for this domain name, which can be self-signed.</para>
37 </listitem>
38 <listitem>
39 <para>A domain, which can run a DNS service that is capable of resolving queries for addresses
40 of the form aaa-bbb-ccc-ddd.yourdomain.com to an IPv4 IP address in the form
41 aaa.bbb.ccc.ddd, for example, 202.8.44.1.</para>
42 </listitem>
43 </itemizedlist>
44 <section id="conoleproxy-ssl">
45 <title>Console Proxy</title>
46 <para>For Console Proxy sessions, you can use one of the following modes: HTTP, HTTPS with
47 wildcard certificate, and HTTPS with a certificate signed under an exact domain name. For each
48 mode, you need to set the global parameter, <parameter>consoleproxy.url.domain</parameter>to
49 different forms of IP address, which can later be resolved by your DNS server. </para>
50 <orderedlist>
51 <listitem>
52 <para>Ensure that you set up a domain in your DNS server.</para>
53 <para>In this example, assume that your DNS server is BIND, and the domain name is
54 yourdomain.com.</para>
55 </listitem>
56 <listitem>
57 <para>Set up your zone in your DNS server. </para>
58 <para>If you are using BIND 9:</para>
59 <programlisting>zone "yourhostip.com" IN {
60 type master;
61 file "yourhostip.com.zone";
62 allow-update { none; };
63 };</programlisting>
64 </listitem>
65 <listitem>
66 <para>Populate an A record for every public IP you have entered in &PRODUCT; that the
67 console proxy could allocate. </para>
68 <para>For example, a range such as 55.66.77.100 to 55.66.77.200.</para>
69 <programlisting>55-66-77-100 IN A 55.66.77.100
70 55-66-77-101 IN A 55.66.77.101
71 55-66-77-102 IN A 55.66.77.102
72 55-66-77-103 IN A 55.66.77.103
73
74 etc..
75
76 55-66-77-200 IN A 55.66.77.200</programlisting>
77 </listitem>
78 <listitem>
79 <para>Update &PRODUCT; with the new domain name:</para>
80 <orderedlist numeration="loweralpha">
81 <listitem>
82 <para>Log in to the &PRODUCT; UI as an administrator.</para>
83 </listitem>
84 <listitem>
85 <para>In the left navigation pane, select Global Settings.</para>
86 </listitem>
87 <listitem>
88 <para>Select the <parameter>consoleproxy.url.domain</parameter> parameter.</para>
89 </listitem>
90 <listitem>
91 <para>Depending on your requirement, perform one of the following:</para>
92 <informaltable>
93 <tgroup cols="3" align="left" colsep="1" rowsep="1">
94 <thead>
95 <row>
96 <entry><para>Console Proxy Mode</para></entry>
97 <entry><para>Global Parameter Settings</para></entry>
98 <entry><para>Console Proxy URL</para></entry>
99 </row>
100 </thead>
101 <tbody>
102 <row>
103 <entry><para>HTTP</para></entry>
104 <entry><para>Set <parameter>consoleproxy.url.domain</parameter> to
105 empty.</para></entry>
106 <entry><para>http://aaa.bbb.ccc.ddd/xxxxx</para>
107 <para>Where xxxxx is the token.</para></entry>
108 </row>
109 <row>
110 <entry><para>HTTPS with wildcard certificate</para></entry>
111 <entry>Set <parameter>consoleproxy.url.domain</parameter> to
112 *.yourdomain.com</entry>
113 <entry><para>http://aaa.bbb.ccc.ddd.yourdomain.com/xxxxx</para>
114 <para>Each public IP entered in &PRODUCT; is converted to a DNS name, for
115 example, 77.88.99.11 and maps to 77-88-99-11.yourdomain.com/xxxxx, where
116 xxxxx is the secure token. When the browser connects to this URL, it try to
117 match to wildcard cert *.yourdomain.com.</para>
118 <para>For more information on generating wildcard certificates, see <xref
119 linkend="change-console-proxy-ssl-certificate-domain"/>.</para></entry>
120 </row>
121 <row>
122 <entry><para>HTTPS with a certificate signed under an exact domain name (load
123 balancing console proxy)</para></entry>
124 <entry><para>Set <parameter>consoleproxy.url.domain</parameter> to
125 xyz.yourdomain.com.</para>
126 </entry>
127 <entry><para>https://xyz.yourdomain.com/xxxxx</para>
128 <para>For more information, see <xref linkend="lb-realhost"/>.</para></entry>
129 </row>
130 </tbody>
131 </tgroup>
132 </informaltable>
133 </listitem>
134 </orderedlist>
135 </listitem>
136 <listitem>
137 <para>Restart the Management Server.</para>
138 </listitem>
139 </orderedlist>
140 </section>
141 <section id="lb-realhost">
142 <title>Load Balancing Console Proxy VMs</title>
143 <orderedlist>
144 <listitem>
145 <para>On an external LB device, such as Citrix Netscaler, configure LB with a name:</para>
146 <orderedlist numeration="loweralpha">
147 <listitem>
148 <para>Create a tagged VLAN.</para>
149 </listitem>
150 <listitem>
151 <para>Assign an IP from the public IP range.</para>
152 <para>For example: 10.10.10.252</para>
153 </listitem>
154 <listitem>
155 <para>Create a virtual server with a virtual IP.</para>
156 <para>For example: 10.10.10.251</para>
157 </listitem>
158 <listitem>
159 <para> Assign the virtual IP to the console proxy VM.</para>
160 </listitem>
161 </orderedlist>
162 </listitem>
163 <listitem>
164 <para>Configure DNS to resolve above hostname to the load balancers IP</para>
165 <orderedlist>
166 <listitem>
167 <para>Edit the forward.named.conf file:</para>
168 <programlisting>@ IN NS xyz.yourdomain.com
169 @ IN A 10.10.10.252
170 xyz IN A 10.10.10.251 </programlisting>
171 <para>The sub domain, xyz, points to the virtual IP of the load balancer.</para>
172 </listitem>
173 <listitem>
174 <para>Restart the service to reflect the changes.</para>
175 </listitem>
176 </orderedlist>
177 </listitem>
178 <listitem id="step3">
179 <para>Start Console Proxy VM to acquire its public IP address.</para>
180 </listitem>
181 <listitem id="step4">
182 <para>Configure the LB rule to point xyz.yourdomain.com to the Console Proxy's IP
183 address.</para>
184 <para>To do that, set the consoleproxy.url.domain to xyz.yourdomain.com.</para>
185 <para>&PRODUCT; sends a request as given below :</para>
186 <programlisting># wget https://xyz.yourdomain.com/ajax?token=<token>token</token></programlisting>
187 <para>&PRODUCT; sends the request to xyz.yourdomain.com, and internally the request is
188 forwarded to the virtual IP of the LB rule, 10.10.10.251. The request is then internally
189 load balanced and forwarded to associated Console Proxy VM.</para>
190 <para>In this example, xyz.yourdomain.com is mapped to the virtual IP of the LB rule on the
191 DNS server. The DNS server resolves the IP and the forward the request to the external LB
192 device. The LB device load balance the request sends to the associated Console Proxy
193 public IP.</para>
194 </listitem>
195 <listitem>
196 <para>Repeat steps <xref linkend="step3"/> and <xref linkend="step4"/> to add more Console Proxy VMs into the LB rule.</para>
197 </listitem>
198 </orderedlist>
199 </section>
200 <section id="ssvm-ssl">
201 <title>Secondary Storage VM</title>
202 <para>Use the <parameter>secstorage.encrypt.copy</parameter> parameter to turn on the secure
203 connection. To customize domain for SSVM, set the
204 <parameter>secstorage.ssl.cert.domain</parameter> parameter to *.yourdomain.com.</para>
205 <note>
206 <para>Provide the full certificate path for the System VMs if you are using a certificate from
207 an intermediate CA. The certificate path begins with the certificate of that certifying
208 entity, and each certificate in the chain is signed by the entity identified by the next
209 certificate in the chain. The chain terminates with a root CA certificate. For browsers to
210 trust the site's certificate, you must specify the full chain: site certificate,
211 intermediate CA, and root CA. Use the uploadCustomCertificate API calls for each level of
212 the chain. The certificate and private key parameters need to have the full text in PEM
213 encoded format. For example: <code>'certificate':'-----BEGIN
214 CERTIFICATE-----\nMIIDYTCCAkmgAwIBAgIQCgEBAQAAAnwasdfKasd</code></para>
215 </note>
216 <para/>
217 </section>
218 <section id="upgrade-sysvm">
219 <title>Upgrade</title>
220 <para>Post upgrade, &PRODUCT; automatically converts the existing domain values, for example
221 yourdomain.com to *.yourdomain.com. After upgrade, modify this value to suit your
222 needs.</para>
223 </section>
224 </section>