Repository: cloudstack-docs Updated Branches: refs/heads/master ffa988fa6 -> cc379373e
realip host changes and cpu sockets changes Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/cc379373 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/cc379373 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/cc379373 Branch: refs/heads/master Commit: cc379373e9fb3e0e21f52c6cf02f2a9b24ca6896 Parents: ffa988f Author: radhikap <[email protected]> Authored: Tue Mar 25 22:56:10 2014 +0530 Committer: radhikap <[email protected]> Committed: Tue Mar 25 22:56:10 2014 +0530 ---------------------------------------------------------------------- en-US/console-proxy.xml | 149 ++++++++-------------------- en-US/cpu-sockets.xml | 7 +- en-US/realip-changes.xml | 224 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 270 insertions(+), 110 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/cc379373/en-US/console-proxy.xml ---------------------------------------------------------------------- diff --git a/en-US/console-proxy.xml b/en-US/console-proxy.xml index 5f9a820..b7aa2c9 100644 --- a/en-US/console-proxy.xml +++ b/en-US/console-proxy.xml @@ -3,20 +3,23 @@ <!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. + 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="console-proxy"> <title>Console Proxy</title> @@ -24,16 +27,17 @@ console view via the web UI. It connects the userâs browser to the VNC port made available via the hypervisor for the console of the guest. Both the administrator and end user web UIs offer a console connection.</para> - <para>Clicking a console icon brings up a new window. The AJAX code downloaded into that window + <para>Clicking on a console icon brings up a new window. The AJAX code downloaded into that window refers to the public IP address of a console proxy VM. There is exactly one public IP address allocated per console proxy VM. The AJAX application connects to this IP. The console proxy then - proxies the connection to the VNC port for the requested VM on the Host hosting the - guest.</para> + proxies the connection to the VNC port for the requested VM on the Host hosting the guest. + .</para> <note> <para>The hypervisors will have many ports assigned to VNC usage so that multiple VNC sessions can occur simultaneously.</para> </note> - <para>There is never any traffic to the guest virtual IP, and there is no need to enable VNC + <para/> + <para>The VNC traffic never goes through the guest virtual IP, and there is no need to enable VNC within the guest.</para> <para>The console proxy VM will periodically report its active session count to the Management Server. The default reporting interval is five seconds. This can be changed through standard @@ -45,96 +49,23 @@ sessions is used.</para> <para>Console proxies can be restarted by administrators but this will interrupt existing console sessions for users.</para> - <section id="use-cert"> - <title>Using a SSL Certificate for the Console Proxy</title> - <para>The console viewing functionality uses a dynamic DNS service under the domain name - realhostip.com to assist in providing SSL security to console sessions. The console proxy is - assigned a public IP address. In order to avoid browser warnings for mismatched SSL - certificates, the URL for the new console window is set to the form of - https://aaa-bbb-ccc-ddd.realhostip.com. You will see this URL during console session creation. - &PRODUCT; includes the realhostip.com SSL certificate in the console proxy VM. Of course, - &PRODUCT; cannot know about the DNS A records for our customers' public IPs prior to shipping - the software. &PRODUCT; therefore runs a dynamic DNS server that is authoritative for the - realhostip.com domain. It maps the aaa-bbb-ccc-ddd part of the DNS name to the IP address - aaa.bbb.ccc.ddd on lookups. This allows the browser to correctly connect to the console - proxy's public IP, where it then expects and receives a SSL certificate for realhostip.com, - and SSL is set up without browser warnings.</para> - </section> - <section id="change-console-proxy-ssl-certificate-domain"> - <title>Changing the Console Proxy SSL Certificate and Domain</title> - <para>If the administrator prefers, it is possible for the URL of the customer's console session - to show a domain other than realhostip.com. The administrator can customize the displayed - domain by selecting a different domain and uploading a new SSL certificate and private key. - The domain must run a DNS service that is capable of resolving queries for addresses of the - form aaa-bbb-ccc-ddd.your.domain to an IPv4 IP address in the form aaa.bbb.ccc.ddd, for - example, 202.8.44.1. To change the console proxy domain, SSL certificate, and private - key:</para> - <orderedlist> - <listitem> - <para>Set up dynamic name resolution or populate all possible DNS names in your public IP - range into your existing DNS server with the format aaa-bbb-ccc-ddd.company.com -> - aaa.bbb.ccc.ddd.</para> - </listitem> - <listitem> - <para>Generate the private key and certificate signing request (CSR). When you are using - openssl to generate private/public key pairs and CSRs, for the private key that you are - going to paste into the &PRODUCT; UI, be sure to convert it into PKCS#8 format.</para> - <orderedlist numeration="loweralpha"> - <listitem> - <para>Generate a new 2048-bit private key</para> - <programlisting>openssl genrsa -des3 -out yourprivate.key 2048</programlisting> - </listitem> - <listitem> - <para>Generate a new certificate CSR</para> - <programlisting>openssl req -new -key yourprivate.key -out yourcertificate.csr</programlisting> - </listitem> - <listitem> - <para>Head to the website of your favorite trusted Certificate Authority, purchase an - SSL certificate, and submit the CSR. You should receive a valid certificate in - return</para> - </listitem> - <listitem> - <para>Convert your private key format into PKCS#8 encrypted format.</para> - <programlisting>openssl pkcs8 -topk8 -in yourprivate.key -out yourprivate.pkcs8.encrypted.key</programlisting> - </listitem> - <listitem> - <para>Convert your PKCS#8 encrypted private key into the PKCS#8 format that is compliant - with &PRODUCT;</para> - <programlisting>openssl pkcs8 -in yourprivate.pkcs8.encrypted.key -out yourprivate.pkcs8.key</programlisting> - </listitem> - </orderedlist> - </listitem> - <listitem> - <para>In the Update SSL Certificate screen of the &PRODUCT; UI, paste the following:</para> - <itemizedlist> - <listitem> - <para>The certificate you've just generated.</para> - </listitem> - <listitem> - <para>The private key you've just generated.</para> - </listitem> - <listitem> - <para>The desired new domain name; for example, company.com</para> - </listitem> - </itemizedlist> - <mediaobject> - <imageobject> - <imagedata fileref="./images/update-ssl.png"/> - </imageobject> - <textobject> - <phrase>updatessl.png: Updating Console Proxy SSL Certificate</phrase> - </textobject> - </mediaobject> - </listitem> - <listitem> - <para>The desired new domain name; for example, company.com</para> - <para>This stops all currently running console proxy VMs, then restarts them with the new - certificate and key. Users might notice a brief interruption in console - availability.</para> - </listitem> - </orderedlist> - <para>The Management Server generates URLs of the form "aaa-bbb-ccc-ddd.company.com" after this - change is made. The new console requests will be served with the new DNS domain name, - certificate, and key.</para> - </section> + <para>Prior to &PRODUCT; version 4.3, the console viewing functionality used a dynamic DNS service + under the domain name realhostip.com. This domain name assists in providing SSL security to + console sessions. A public IP address is assigned to the console proxy. To avoid browser + warnings for mismatched SSL certificates, the URL for the new console window was set to the form + of https://aaa-bbb-ccc-ddd.realhostip.com. Customers viewed this URL during the console session + creation. &PRODUCT; included the realhostip.com SSL certificate in the console proxy VM. Because + &PRODUCT; cannot know the DNS records of customers' public IPs prior to shipping the software, a + dynamic DNS server is run that is authoritative for the realhostip.com domain. It mapped the + aaa-bbb-ccc-ddd part of the DNS name to the IP address aaa.bbb.ccc.ddd on lookups. This allowed + the browser to correctly connect to the console proxy's public IP, where it then expects and + receives a SSL certificate for realhostip.com, and SSL is set up without browser + warnings.</para> + <para>The realhostip.com domain has now been depreciated. As an alternate, &PRODUCT; provides a + new mechanism based on global settings to help administrators set up secure connections across + various deployment environments. See <xref linkend="realip-changes"/> for information on setting + up own domain, then customize the URL of your console session to reflect your own domain + name.</para> + <xi:include href="change-console-proxy-ssl-certificate-domain.xml" + xmlns:xi="http://www.w3.org/2001/XInclude"/> </section> http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/cc379373/en-US/cpu-sockets.xml ---------------------------------------------------------------------- diff --git a/en-US/cpu-sockets.xml b/en-US/cpu-sockets.xml index f435976..2fd592d 100644 --- a/en-US/cpu-sockets.xml +++ b/en-US/cpu-sockets.xml @@ -28,7 +28,7 @@ infrastructure. &PRODUCT; provides both UI and API support to collect the CPU socket statistics for billing purpose. The Infrastructure tab has a new tab for CPU sockets. You can view the statistics for CPU sockets managed by &PRODUCT;, which in turn reflects the size of the cloud. - The CPU Socket page will give you the number of hosts and sockets used for each host + The CPU Socket page will give you the number of hosts and sockets used for each hypervisor type.</para> <orderedlist> <listitem> @@ -41,6 +41,11 @@ <para>On CPU Sockets, click View all.</para> <para>The CPU Socket page is displayed. The page shows the number of hosts and CPU sockets based on hypervisor types.</para> + <para>CPU sockets are displayed for XenServer version 6.2 and beyond, KVM, Hyper-V and VMware + hypervisors.</para> + <para>This feature is not available for XenServer versions prior to 6.2 as they don't support + retrieving CPU socket information. Additionally, this feature is not supported for + Baremetal.</para> </listitem> </orderedlist> </section> http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/cc379373/en-US/realip-changes.xml ---------------------------------------------------------------------- diff --git a/en-US/realip-changes.xml b/en-US/realip-changes.xml new file mode 100644 index 0000000..6b9d904 --- /dev/null +++ b/en-US/realip-changes.xml @@ -0,0 +1,224 @@ +<?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>
