| <?xml version='1.0' encoding='utf-8' ?> |
| <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
| <!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> |
| %BOOK_ENTITIES; |
| ]> |
| |
| <!-- Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <section id="realip-changes"> |
| <title>Secure Connections for &PRODUCT;System VMs</title> |
| <para>&PRODUCT; System VMs, such as console proxy and Secondary storage VMs, use SSL certificates |
| to host HTTPS connections. Because each &PRODUCT; environment is unique, System VMs in each |
| deployment varies and each instance will have its own set of IP addresses. To use one SSL |
| certificate across all the instances among different deployments, &PRODUCT; provides a global |
| parameter based mechanism. To achieve that you need the following:</para> |
| <itemizedlist> |
| <listitem> |
| <para>A software that runs a wildcard DNS service.</para> |
| </listitem> |
| <listitem> |
| <para>A wildcard certificate for this domain name, which can be self-signed.</para> |
| </listitem> |
| <listitem> |
| <para>A domain, which can run a DNS service that is capable of resolving queries for addresses |
| of the form aaa-bbb-ccc-ddd.yourdomain.com to an IPv4 IP address in the form |
| aaa.bbb.ccc.ddd, for example, 202.8.44.1.</para> |
| </listitem> |
| </itemizedlist> |
| <section id="conoleproxy-ssl"> |
| <title>Console Proxy</title> |
| <para>For Console Proxy sessions, you can use one of the following modes: HTTP, HTTPS with |
| wildcard certificate, and HTTPS with a certificate signed under an exact domain name. For each |
| mode, you need to set the global parameter, <parameter>consoleproxy.url.domain</parameter>to |
| different forms of IP address, which can later be resolved by your DNS server. </para> |
| <orderedlist> |
| <listitem> |
| <para>Ensure that you set up a domain in your DNS server.</para> |
| <para>In this example, assume that your DNS server is BIND, and the domain name is |
| yourdomain.com.</para> |
| </listitem> |
| <listitem> |
| <para>Set up your zone in your DNS server. </para> |
| <para>If you are using BIND 9:</para> |
| <programlisting>zone "yourhostip.com" IN { |
| type master; |
| file "yourhostip.com.zone"; |
| allow-update { none; }; |
| };</programlisting> |
| </listitem> |
| <listitem> |
| <para>Populate an A record for every public IP you have entered in &PRODUCT; that the |
| console proxy could allocate. </para> |
| <para>For example, a range such as 55.66.77.100 to 55.66.77.200.</para> |
| <programlisting>55-66-77-100 IN A 55.66.77.100 |
| 55-66-77-101 IN A 55.66.77.101 |
| 55-66-77-102 IN A 55.66.77.102 |
| 55-66-77-103 IN A 55.66.77.103 |
| |
| etc.. |
| |
| 55-66-77-200 IN A 55.66.77.200</programlisting> |
| </listitem> |
| <listitem> |
| <para>Update &PRODUCT; with the new domain name:</para> |
| <orderedlist numeration="loweralpha"> |
| <listitem> |
| <para>Log in to the &PRODUCT; UI as an administrator.</para> |
| </listitem> |
| <listitem> |
| <para>In the left navigation pane, select Global Settings.</para> |
| </listitem> |
| <listitem> |
| <para>Select the <parameter>consoleproxy.url.domain</parameter> parameter.</para> |
| </listitem> |
| <listitem> |
| <para>Depending on your requirement, perform one of the following:</para> |
| <informaltable> |
| <tgroup cols="3" align="left" colsep="1" rowsep="1"> |
| <thead> |
| <row> |
| <entry><para>Console Proxy Mode</para></entry> |
| <entry><para>Global Parameter Settings</para></entry> |
| <entry><para>Console Proxy URL</para></entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><para>HTTP</para></entry> |
| <entry><para>Set <parameter>consoleproxy.url.domain</parameter> to |
| empty.</para></entry> |
| <entry><para>http://aaa.bbb.ccc.ddd/xxxxx</para> |
| <para>Where xxxxx is the token.</para></entry> |
| </row> |
| <row> |
| <entry><para>HTTPS with wildcard certificate</para></entry> |
| <entry>Set <parameter>consoleproxy.url.domain</parameter> to |
| *.yourdomain.com</entry> |
| <entry><para>http://aaa.bbb.ccc.ddd.yourdomain.com/xxxxx</para> |
| <para>Each public IP entered in &PRODUCT; is converted to a DNS name, for |
| example, 77.88.99.11 and maps to 77-88-99-11.yourdomain.com/xxxxx, where |
| xxxxx is the secure token. When the browser connects to this URL, it try to |
| match to wildcard cert *.yourdomain.com.</para> |
| <para>For more information on generating wildcard certificates, see <xref |
| linkend="change-console-proxy-ssl-certificate-domain"/>.</para></entry> |
| </row> |
| <row> |
| <entry><para>HTTPS with a certificate signed under an exact domain name (load |
| balancing console proxy)</para></entry> |
| <entry><para>Set <parameter>consoleproxy.url.domain</parameter> to |
| xyz.yourdomain.com.</para> |
| </entry> |
| <entry><para>https://xyz.yourdomain.com/xxxxx</para> |
| <para>For more information, see <xref linkend="lb-realhost"/>.</para></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| <listitem> |
| <para>Restart the Management Server.</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| <section id="lb-realhost"> |
| <title>Load Balancing Console Proxy VMs</title> |
| <orderedlist> |
| <listitem> |
| <para>On an external LB device, such as Citrix Netscaler, configure LB with a name:</para> |
| <orderedlist numeration="loweralpha"> |
| <listitem> |
| <para>Create a tagged VLAN.</para> |
| </listitem> |
| <listitem> |
| <para>Assign an IP from the public IP range.</para> |
| <para>For example: 10.10.10.252</para> |
| </listitem> |
| <listitem> |
| <para>Create a virtual server with a virtual IP.</para> |
| <para>For example: 10.10.10.251</para> |
| </listitem> |
| <listitem> |
| <para> Assign the virtual IP to the console proxy VM.</para> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| <listitem> |
| <para>Configure DNS to resolve above hostname to the load balancers IP</para> |
| <orderedlist> |
| <listitem> |
| <para>Edit the forward.named.conf file:</para> |
| <programlisting>@ IN NS xyz.yourdomain.com |
| @ IN A 10.10.10.252 |
| xyz IN A 10.10.10.251 </programlisting> |
| <para>The sub domain, xyz, points to the virtual IP of the load balancer.</para> |
| </listitem> |
| <listitem> |
| <para>Restart the service to reflect the changes.</para> |
| </listitem> |
| </orderedlist> |
| </listitem> |
| <listitem id="step3"> |
| <para>Start Console Proxy VM to acquire its public IP address.</para> |
| </listitem> |
| <listitem id="step4"> |
| <para>Configure the LB rule to point xyz.yourdomain.com to the Console Proxy's IP |
| address.</para> |
| <para>To do that, set the consoleproxy.url.domain to xyz.yourdomain.com.</para> |
| <para>&PRODUCT; sends a request as given below :</para> |
| <programlisting># wget https://xyz.yourdomain.com/ajax?token=<token>token</token></programlisting> |
| <para>&PRODUCT; sends the request to xyz.yourdomain.com, and internally the request is |
| forwarded to the virtual IP of the LB rule, 10.10.10.251. The request is then internally |
| load balanced and forwarded to associated Console Proxy VM.</para> |
| <para>In this example, xyz.yourdomain.com is mapped to the virtual IP of the LB rule on the |
| DNS server. The DNS server resolves the IP and the forward the request to the external LB |
| device. The LB device load balance the request sends to the associated Console Proxy |
| public IP.</para> |
| </listitem> |
| <listitem> |
| <para>Repeat steps <xref linkend="step3"/> and <xref linkend="step4"/> to add more Console Proxy VMs into the LB rule.</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| <section id="ssvm-ssl"> |
| <title>Secondary Storage VM</title> |
| <para>Use the <parameter>secstorage.encrypt.copy</parameter> parameter to turn on the secure |
| connection. To customize domain for SSVM, set the |
| <parameter>secstorage.ssl.cert.domain</parameter> parameter to *.yourdomain.com.</para> |
| <note> |
| <para>Provide the full certificate path for the System VMs if you are using a certificate from |
| an intermediate CA. The certificate path begins with the certificate of that certifying |
| entity, and each certificate in the chain is signed by the entity identified by the next |
| certificate in the chain. The chain terminates with a root CA certificate. For browsers to |
| trust the site's certificate, you must specify the full chain: site certificate, |
| intermediate CA, and root CA. Use the uploadCustomCertificate API calls for each level of |
| the chain. The certificate and private key parameters need to have the full text in PEM |
| encoded format. For example: <code>'certificate':'-----BEGIN |
| CERTIFICATE-----\nMIIDYTCCAkmgAwIBAgIQCgEBAQAAAnwasdfKasd</code></para> |
| </note> |
| <para/> |
| </section> |
| <section id="upgrade-sysvm"> |
| <title>Upgrade</title> |
| <para>Post upgrade, &PRODUCT; automatically converts the existing domain values, for example |
| yourdomain.com to *.yourdomain.com. After upgrade, modify this value to suit your |
| needs.</para> |
| </section> |
| </section> |
