You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by se...@apache.org on 2014/02/20 16:00:58 UTC
[02/34] refactor docs repo
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/cb915b74/release-notes/en-US/Release_Notes.xml
----------------------------------------------------------------------
diff --git a/release-notes/en-US/Release_Notes.xml b/release-notes/en-US/Release_Notes.xml
deleted file mode 100644
index 7233370..0000000
--- a/release-notes/en-US/Release_Notes.xml
+++ /dev/null
@@ -1,3304 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE book 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.
--->
-<book>
- <xi:include href="Book_Info_Release_Notes_4.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- <chapter id="welcome-4.3">
- <title>Welcome to &PRODUCT; 4.3</title>
- <para>Welcome to the 4.3 release of &PRODUCT;. This version is the first feature release of
- &PRODUCT; in the 4.3.<emphasis role="italic">x</emphasis> line.</para>
- <para>This document contains information specific to this release of &PRODUCT;, including
- upgrade instructions from prior releases, new features added to &PRODUCT;, API changes, and
- issues fixed in the release. For installation instructions, please see the <ulink
- url="http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.3.0/html/Installation_Guide/index.html"
- >Installation Guide</ulink>. For usage and administration instructions, please see the
- <ulink
- url="http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.3.0/html/Admin_Guide/index.html"
- >&PRODUCT; Administrator's Guide</ulink>. Developers and users who wish to work with the API
- will find instruction in the <ulink
- url="http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/API_Developers_Guide/index.html"
- >&PRODUCT; API Developer's Guide</ulink>.</para>
- <para>If you find any errors or problems in this guide, please see <xref linkend="feedback"/>.
- We hope you enjoy working with &PRODUCT;!</para>
- </chapter>
- <chapter id="supported-os">
- <title>Compatibility Matrix</title>
- <para>This section describes the operating systems, browsers, and hypervisors that have been
- newly tested and certified compatible with &PRODUCT; 4.3. Most earlier OS and hypervisor
- versions are also still supported for use with 4.3 It might work well on other platforms, but
- the platforms listed below are the ones that are specifically tested against and are more
- likely to be able to help troubleshoot if you run into any issues.</para>
- <section id="management-server">
- <title>Supported OS Versions for Management Server</title>
- <para>This section lists the operating systems that are supported for running &PRODUCT;
- Management Server. Note that specific versions of the operating systems are tested, so
- compatibility with CentOS 6.3 may not indicate compatibility with CentOS 6.2, 6.1 and so
- on.</para>
- <itemizedlist>
- <listitem>
- <para>RHEL versions 5.5, 6.2, 6.3, and 6.4</para>
- </listitem>
- <listitem>
- <para>CentOS versions 6.3, and 6.4</para>
- </listitem>
- <listitem>
- <para>Ubuntu 12.04 LTS</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="supported-hv">
- <title>Supported Hypervisor Versions</title>
- <para>CloudStack supports three hypervisor families, XenServer with XAPI, KVM, and VMware with
- vSphere.</para>
- <itemizedlist>
- <listitem>
- <para>Windows Server 2012 R2 (with Hyper-V Role enabled)</para>
- </listitem>
- <listitem>
- <para>Hyper-V 2012 R2</para>
- </listitem>
- <listitem>
- <para>CentOS 6.2 with KVM</para>
- </listitem>
- <listitem>
- <para>Red Hat Enterprise Linux 6.2 with KVM</para>
- </listitem>
- <listitem>
- <para>XenServer 6.0.2 (with Hotfix)</para>
- </listitem>
- <listitem>
- <para>XenServer versions 6.1 and 6.2 SPI with latest hotfixes</para>
- </listitem>
- <listitem>
- <para>VMware versions 5.0, 5.1, and 5.5</para>
- </listitem>
- <listitem>
- <para>Bare metal hosts are supported, which have no hypervisor. These hosts can run the
- following operating systems:</para>
- <itemizedlist>
- <listitem>
- <para>RHEL or CentOS, v6.2 or 6.3</para>
- <note>
- <para>Use libvirt version 0.9.10 for CentOS 6.3</para>
- </note>
- </listitem>
- <listitem>
- <para>Fedora 17</para>
- </listitem>
- <listitem>
- <para>Ubuntu 12.04</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>For more information, see the Hypervisor Compatibility Matrix in the &PRODUCT;
- Installation Guide.</para>
- </section>
- <section id="ex-devices">
- <title>Supported External Devices</title>
- <itemizedlist>
- <listitem>
- <para>Netscaler VPX and MPX versions 9.3 and 10.e </para>
- </listitem>
- <listitem>
- <para>Netscaler SDX version 9.3</para>
- </listitem>
- <listitem>
- <para>SRX (Model srx100b) versions 10.3 or higher</para>
- </listitem>
- <listitem>
- <para>F5 10.1.0 (Build 3341.1084)</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="browser">
- <title>Supported Browsers</title>
- <para>The &PRODUCT; Web-based UI should be compatible with any modern browser, but it's
- possible that some browsers will not render portions of the UI reliably, depending on their
- support of Web standards. For best results, one of the following browsers
- recommended:</para>
- <itemizedlist>
- <listitem>
- <para>Internet Explorer versions 10 and 11</para>
- </listitem>
- <listitem>
- <para>Firefox version 26 or lower</para>
- </listitem>
- <listitem>
- <para>Google Chrome version 31</para>
- </listitem>
- <listitem>
- <para>Safari 5</para>
- </listitem>
- </itemizedlist>
- </section>
- </chapter>
- <chapter id="version-4.3">
- <title>About This New Release</title>
- <section id="whats-new-in-4.3">
- <title>What's New in 4.3</title>
- <para>&PRODUCT; 4.3 includes the following new features.</para>
- <section id="xen64-bit-temp">
- <title>Optional 64-Bit System VM Template Support</title>
- <para>&PRODUCT; now provides 64-bit templates for System VMs. With this support, you will be
- able to upgrade virtual routers in a zone. The following parameters have been introduced
- for the same purpose:</para>
- <itemizedlist>
- <listitem>
- <para>XenServer: <parameter>router.template.xen</parameter></para>
- </listitem>
- <listitem>
- <para>KVM: <parameter>router.template.kvm</parameter></para>
- </listitem>
- <listitem>
- <para>VMware:</para>
- </listitem>
- <listitem>
- <para>Hyper-V:</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="hyperv">
- <title>Hyper-V Support</title>
- <para>&PRODUCT; 4.3 Beta rolls out support for Hyper-V hosts. For Hyper-V, &PRODUCT;
- supports SMB-based storage. If you want to run guest VMs on Hyper-V hosts, install
- &PRODUCT; Agents on each Hyper-V hosts. Before you use Hyper-V, review the following list
- of supported and non-supported features. For detailed instruction, see Hyper-V Quick Start
- Guide. You can also see the chapter Installing Hyper-V for &PRODUCT; in the &PRODUCT; 4.3
- Beta Installation Guide.</para>
- <section id="supported-functions">
- <title>Supported Functionalities</title>
- <itemizedlist>
- <listitem>
- <para>VM Compute</para>
- <itemizedlist>
- <listitem>
- <para>All the VM operations, except VM Snapshots</para>
- </listitem>
- <listitem>
- <para>Live Migration</para>
- </listitem>
- <listitem>
- <para>Service Offerings (Scale up on stopped VMs)</para>
- </listitem>
- <listitem>
- <para>Console access</para>
- </listitem>
- <listitem>
- <para>SSH key and reseting SSH key</para>
- </listitem>
- <listitem>
- <para>Upload and download templates, volumes, and ISO</para>
- </listitem>
- <listitem>
- <para>Create VMs from template and ISO</para>
- </listitem>
- <listitem>
- <para>Create template from volume</para>
- </listitem>
- <listitem>
- <para>Attach and detach VMs from ISO and password-enabled template</para>
- </listitem>
- <listitem>
- <para>Copy template across zone</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Storage</para>
- <itemizedlist>
- <listitem>
- <para>Primary Storage (SMB and Local)</para>
- </listitem>
- <listitem>
- <para>Root and data volumes on Local and SMB</para>
- </listitem>
- <listitem>
- <para>Add, delete, attach, detach volumes (one or more volumes per VM)</para>
- </listitem>
- <listitem>
- <para>Single and multiple secondary storage (SMB)</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Network</para>
- <itemizedlist>
- <listitem>
- <para>VLANs (Isolated and Shared)</para>
- </listitem>
- <listitem>
- <para>All VR services: DNS, DHCP, SourceNAT, LB, PF, Firewall, StaticNAT,
- Userdata, and VPN</para>
- </listitem>
- <listitem>
- <para>External device support for both Isolated and Shared networks: Netscaler,
- SRX, F5</para>
- </listitem>
- <listitem>
- <para>Multiple physical networks</para>
- </listitem>
- <listitem>
- <para>Dedicated IP range, Public VLANs (to account)</para>
- </listitem>
- <listitem>
- <para>Network Offering upgrades and updates</para>
- </listitem>
- <listitem>
- <para>L4-L7 services in Shared network</para>
- </listitem>
- <listitem>
- <para>Multiple IP ranges and portable IPs</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Host and Storage in maintenance mode</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="unsupported-hyperv">
- <title>Unsupported Functionalities</title>
- <itemizedlist>
- <listitem>
- <para>Affinity an Anti-Affinity Groups</para>
- </listitem>
- <listitem>
- <para>Network throttling </para>
- </listitem>
- <listitem>
- <para>Security groups (Advanced Zone)</para>
- </listitem>
- <listitem>
- <para>IPv6</para>
- </listitem>
- <listitem>
- <para>Snapshot: VM and disk</para>
- </listitem>
- <listitem>
- <para>PVLAN</para>
- </listitem>
- <listitem>
- <para>VPC</para>
- </listitem>
- <listitem>
- <para>HA of guest VMs</para>
- </listitem>
- <listitem>
- <para>Redundant VR</para>
- </listitem>
- <listitem>
- <para>Object Store</para>
- </listitem>
- <listitem>
- <para>Mixed hypervisor zone</para>
- </listitem>
- <listitem>
- <para>Zone-wide Primary storage</para>
- </listitem>
- <listitem>
- <para>NIC bonding</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section id="sysvm-upgrade">
- <title>Enhanced Upgrade for Virtual Routers</title>
- <para>Upgrading VRs is made flexible. The &PRODUCT; administrators will be able to control
- the sequence of the VR upgrades. The sequencing is based on Infrastructure hierarchy, such
- as by Cluster, Pod, or Zone, and Administrative hierarchy, such as by Tenant or Domain.
- This implies, for example, that you will have the flexibility to upgrade a VR in a
- specified zone. As an administrator, you can also determine when a particular VR can be
- upgraded within a specified upgrade interval. Additionally, upgrade operation is enhanced
- to increase the upgrade speed by allowing as many upgrade operations in parallel as
- possible. During the entire duration of the upgrade, users cannot launch new services or
- make changes to an existing service.</para>
- <para>To support this feature, a new API, upgradeRouterTemplate, has been introduced.</para>
- <para>The detailed instruction is provided in the &PRODUCT; 4.3 Beta Administration Guide.
- See section 17.5.5. Enhanced Upgrade for Virtual Routers.</para>
- </section>
- <section id="monitor-vr">
- <title>Service Monitoring Tool for Virtual Router</title>
- <para>Various services running on the &PRODUCT; virtual routers can be monitored by using a
- Service Monitoring tool. The tool ensures that services are successfully running until
- &PRODUCT; deliberately disables them. If a service goes down, the tool automatically
- performs a restart, and if that does not help bringing up the service, an alert as well as
- an event is generated indicating the failure.</para>
- <para>The following services are monitored in a VR:</para>
- <itemizedlist>
- <listitem>
- <para>DNS</para>
- </listitem>
- <listitem>
- <para>HA Proxy</para>
- </listitem>
- <listitem>
- <para>SSH</para>
- </listitem>
- <listitem>
- <para>Apache Web Server</para>
- </listitem>
- </itemizedlist>
- <para>Only the services with daemons are monitored.</para>
- <para>The following networks are supported:</para>
- <itemizedlist>
- <listitem>
- <para>Isolated Networks</para>
- </listitem>
- <listitem>
- <para>Shared Networks in both Advanced and Basic zone</para>
- </listitem>
- </itemizedlist>
- <para>This feature is supported on the following hypervisors: XenServer, VMware, and
- KVM.</para>
- <para>The detailed instruction is provided in the &PRODUCT; 4.3 Beta Administration Guide.
- See section 17.5.4. Service Monitoring Tool for Virtual Router.</para>
- </section>
- <section id="dynamic-compute-offering">
- <title>Custom Compute Offering</title>
- <para>&PRODUCT; provides you the flexibility to specify the desired values for the number of
- CPU, CPU speed, and memory while deploying a VM. The admin creates a Compute Offering by
- marking it as custom, and as an user, you will be able to customize this dynamic Compute
- Offering by specifying the memory, CPU and root disk at the time of VM creation or
- upgrade.</para>
- <para>Custom Compute Offering is same as the normal Compute Offering except that the values
- of the dynamic parameters will be set to zeros in the given set of templates. Use this
- offering to deploy VM by specifying custom values for the dynamic parameters. Memory, CPU
- and number of CPUs are considered as dynamic parameters. Dynamic Compute Offerings can be
- used in following cases: deploying a VM, changing the compute offering of a stopped VM and
- running VMs, which is nothing but scaling up. To support this feature a new field, Custom,
- has been added to the Create Compute Offering page. If the Custom field is checked, the
- end-user will be able to create a custom Compute Offering by filling in the desired values
- for number of CPU, CPU speed, and memory. </para>
- </section>
- <section id="remote-vpn-vpc">
- <title>Remote Access VPN for VPC</title>
- <para>Support for Remote access VPN in Isolated networks is now extended to VPC networks.
- Remote users will now be able to initiate a VPN connection to a VPC network. To enable
- this feature, enable VPN in the Source NAT IP of the VPC.</para>
- </section>
- <section id="site-site-vpn-vr">
- <title>Site to Site VPN Connection Between VPC Networks</title>
- <para>&PRODUCT; provides you with the ability to establish a site-to-site VPN connection
- between &PRODUCT; virtual routers. With this functionality, users can deploy applications
- in multiple Availability Zones or VPCs, which can communicate with each other by using a
- secure Site-to-Site VPN Tunnel. Creating a typical Site to Site VPN connection between VPC
- networks involves the following:</para>
- <orderedlist>
- <listitem>
- <para>Create two VPCs. For example, VPC A and VPC B.</para>
- </listitem>
- <listitem>
- <para>Create VPN gateways on both the VPCs you created.</para>
- </listitem>
- <listitem>
- <para>Create VPN customer gateway for both the VPCs.</para>
- </listitem>
- <listitem>
- <para>Enable a VPN connection on VPC A in passive mode. </para>
- <para>Ensure that the customer gateway is pointed to VPC B. The VPN connection is shown
- in the Disconnected state.</para>
- </listitem>
- <listitem>
- <para>Enable a VPN connection on VPC B. </para>
- <para>Ensure that the customer gateway is pointed to VPC A. Because virtual router of
- VPC A, in this case, is in passive mode and is waiting for the virtual router of VPC B
- to initiate the connection. The virtual router of VPC B should not be in passive mode. </para>
- <para>The VPN connection is shown in the Disconnected state. </para>
- <para>Creating VPN connection on both the VPCs initiates a VPN connection. Wait for few
- seconds. The default is 30 seconds for both the VPN connections to show the Connected
- state.</para>
- </listitem>
- </orderedlist>
- </section>
- <section id="cpu-sockets">
- <title>Reporting CPU Sockets</title>
- <para>&PRODUCT; now provides an additional infrastructure statistics for CPU sockets managed
- by &PRODUCT;, which in turn reflects the size of the cloud. The Infrastructure tab has a
- new tab for sockets. The Socket page will give you the number of hosts an sockets used for
- each hypervisor type. This feature is not supported in versions prior to XenServer
- 6.2.</para>
- </section>
- <section id="ha-db">
- <title>Database High Availability</title>
- <para>To help ensure high availability of the databases that store the internal data for
- &PRODUCT;, you can set up database replication. This covers both the main &PRODUCT;
- database and the Usage database. Replication is achieved using the MySQL connector
- parameters and two-way replication. Tested with MySQL 5.1 and 5.5. Database replication in
- &PRODUCT; is provided using the MySQL replication capabilities. The steps to set up
- replication can be found in the MySQL documentation.</para>
- </section>
- <section id="ldap-provisoion">
- <title>LDAP User Provisioning</title>
- <para>LDAP user provisioning has been enhanced by allowing user import from the configured
- LDAP servers. You will be able to add multiple LDAP servers and selectively import LDAP
- users. You can o filter by group name and import all the users within a group. After they
- have been imported to &PRODUCT;, in contrast to manually adding them in previous releases,
- users are allowed to directly log in to &PRODUCT; by using the LDAP credentials.</para>
- </section>
- <section id="migrate-nfs-objectstore">
- <title>Migrating NFS Secondary Storage to Object Store</title>
- <para>In an existing zone that is using NFS for secondary storage, you can upgrade the zone
- to use a region-wide object storage without causing downtime. The existing NFS storage in
- the zone will be converted to an NFS Staging Store. After migration, the data that was on
- the NFS storage remains there. &PRODUCT; does not provide a way to automatically migrate
- all data to the new object storage. The data remaining on the old NFS storage will remain
- accessible for read and delete operations only. Newly created snapshots and templates will
- be placed in the newly configured object storage. </para>
- </section>
- <section id="vxlan-plugin">
- <title>VXLAN Plugin Support</title>
- <para>The VXLAN plugin adds VXLAN as one of the guest network isolation methods in
- &PRODUCT;. This plugin enables more than 4096 isolated guest networks in a Zone, with
- almost the same usability as VLAN isolation. This plugin provides no network services. Use
- virtual router for network services. This plugin is supported on KVM hypervisors.</para>
- </section>
- <section id="contrail-plugin">
- <title>Contrail Network Plugin Support</title>
- <para>The Contrail virtual network controller is an open source project that provides an
- overlay implementation of network virtualization that is interoperable with network
- devices that support existing network virtualization standards. Support for the Contrail
- plugin has been added to &PRODUCT; to provide NAT services to the XenServer hosts. The
- plugin supports isolated networks, Static NAT implemented by the VRouter dataplane, and
- Source NAT implemented by using a virtual appliance with full NAT functionality.</para>
- </section>
- <section id="alert-publish">
- <title>Publishing Alert Using the Web ROOT Admin API</title>
- <para>In previous releases of &PRODUCT; code alerts are generated for &PRODUCT; services
- (Usage service) only if they run on the same host as the Management Server. A new API has
- been introduced in 4.3, which can be used by the following services to generate and
- publish. The services need not be running on the same host where the Management Server is
- running.</para>
- <itemizedlist>
- <listitem>
- <para>Any new services added to &PRODUCT;.</para>
- </listitem>
- <listitem>
- <para>Usage service when run on a separate storage host.</para>
- </listitem>
- <listitem>
- <para>Console Proxy and Secondary Storage VM services.</para>
- </listitem>
- </itemizedlist>
- <para>The main advantage of this feature is that the third party systems integrating with
- &PRODUCT; will be able to utilize the Alert notification system publish alerts. </para>
- </section>
- <section id="palo-alto">
- <title>Support for Palo Alto Firewall Service</title>
- <para>&PRODUCT; supports Palo Alto firewall services. Use the Create Network Offering dialog
- to create an offering which has the Palo Alto firewall services. What is not supported and
- not supported are given below:</para>
- <section id="supported-palo-alto">
- <title>Supported Functionalities</title>
- <itemizedlist>
- <listitem>
- <para>Advanced Network</para>
- </listitem>
- <listitem>
- <para>Parallel deployment with hardware Load balancer</para>
- </listitem>
- <listitem>
- <para>Virtual Palo Alto firewall.</para>
- </listitem>
- <listitem>
- <para>Communication layer with Palo Alto APIs.</para>
- </listitem>
- <listitem>
- <para>Mapping of CloudStack APIs to corresponding Palo Alto APIs.</para>
- </listitem>
- <listitem>
- <para>Connectivity status of the firewall service on the &PRODUCT; UI.</para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="notsupported-palo-alto">
- <title>Unsupported Functionalities</title>
- <itemizedlist>
- <listitem>
- <para>Inline deployment with hardware Load balancer </para>
- </listitem>
- <listitem>
- <para>Firewall between VLANs within an advanced network</para>
- </listitem>
- <listitem>
- <para>Firewall between VM instances</para>
- </listitem>
- </itemizedlist>
- <para>For more information, see <ulink
- url="https://cwiki.apache.org/confluence/display/CLOUDSTACK/Palo+Alto+Firewall+Integration"
- >Palo Alto Firewall Integration</ulink>.</para>
- </section>
- </section>
- <section id="root-volume-metering">
- <title>Root Volume Metering</title>
- <para>&PRODUCT; supports recording usage events as per the dynamically assigned resources.
- Usage events are registered when a VM is created from dynamic service offering, and the
- values of parameters, such as CPU, speed, RAM are recorded. If VM is deployed by using
- template and dynamic root disk size is mentioned, the same value is recorded in the usage
- event.</para>
- </section>
- <section id="ssl-termination">
- <title>Support for SSL Termination</title>
- <para>SSL Offloading allows load balancers to handle encryption and decryption of HTTP(s)
- traffic giving plain text HTTP to the back end servers freeing them from the resource
- intensive task of handling encryption and decryption. Supported for Citrix
- NetScaler.</para>
- </section>
- <section id="pluggable-vm-snapshot">
- <title>Support for Pluggable VM Snapshots</title>
- <para>&PRODUCT; implements a plugin to integrate a third-party storage provider. Third party
- storage providers can integrate with &PRODUCT; to provide either primary storage or
- secondary storage. The user enables a storage plugin through the UI. A new dialog box
- choice is offered to select the storage provider. Depending on which provider is selected,
- additional input fields may appear so that the user can provide the additional details
- required by that provider, such as a user name and password for a third-party storage
- account.</para>
- </section>
- <section id="new-ui">
- <title>Enhanced &PRODUCT; UI</title>
- <para>A complete UI makeover is implemented to enhance the usability and user experience in
- modern browsers. The visual look-and-feel has been changed for the Header, Navigation,
- Buttons, text fields, drop-downs, tables and so on. Consistent color themes has been
- introduced to match with the Apache branding. </para>
- <para>The current UI flow remains the same.</para>
- </section>
- </section>
- <section id="issues-fixed-4.3">
- <title>Issues Fixed in 4.3.0</title>
- <para>Apache CloudStack uses <ulink url="https://issues.apache.org/jira/browse/CLOUDSTACK"
- >Jira</ulink> to track its issues. All new features and bugs for 4.3 have been tracked in
- Jira, and have a standard naming convention of "CLOUDSTACK-NNNN" where "NNNN" is the issue
- number.</para>
- <para>For the list of issues fixed, see <ulink
- url="https://issues.apache.org/jira/issues/?filter=12326161">Issues Fixed in
- 4.3</ulink>.</para>
- </section>
- <section id="known-issues-4.3">
- <title>Known Issues in 4.3.0</title>
- <para>Apache CloudStack uses <ulink url="https://issues.apache.org/jira/browse/CLOUDSTACK"
- >Jira</ulink> to track its issues. All new features and bugs for 4.3 have been tracked in
- Jira, and have a standard naming convention of "CLOUDSTACK-NNNN" where "NNNN" is the issue
- number.</para>
- <para>For the list of known issues, see <ulink
- url="https://issues.apache.org/jira/issues/?filter=12326162">Known Issues in
- 4.3</ulink>.</para>
- </section>
- </chapter>
- <chapter id="upgrade-instructions-4.3">
- <title>Upgrade Instructions for 4.3</title>
- <para>This section contains upgrade instructions from prior versions of CloudStack to Apache
- CloudStack 4.3. We include instructions on upgrading to Apache CloudStack from pre-Apache
- versions of Citrix &PRODUCT; (last version prior to Apache is 3.0.2) and from the releases
- made while CloudStack was in the Apache Incubator.</para>
- <para>If you run into any issues during upgrades, please feel free to ask questions on
- users@cloudstack.apache.org or dev@cloudstack.apache.org.</para>
- <section id="upgrade-from-4.2-to-4.3">
- <title>Upgrade from 4.2.0 to 4.3</title>
- <para>This section will guide you from &PRODUCT; 4.2 to &PRODUCT; 4.3.</para>
- <para>Any steps that are hypervisor-specific will be called out with a note.</para>
- <para>We recommend reading through this section once or twice before beginning your upgrade
- procedure, and working through it on a test system before working on a production
- system.</para>
- <orderedlist>
- <note>
- <para>The following upgrade instructions should be performed regardless of hypervisor
- type.</para>
- </note>
- <listitem>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>While running the existing 4.2.0 system, log in to the UI as root
- administrator.</para>
- </listitem>
- <listitem>
- <para>In the left navigation bar, click Templates.</para>
- </listitem>
- <listitem>
- <para>In Select view, click Templates.</para>
- </listitem>
- <listitem>
- <para>Click Register template.</para>
- <para>The Register template dialog box is displayed.</para>
- </listitem>
- <listitem>
- <para>In the Register template dialog box, specify the following values (do not change
- these):</para>
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="1">
- <colspec colwidth="1*" colname="1" colnum="1"/>
- <colspec colwidth="2*" colname="2" colnum="2"/>
- <thead>
- <row>
- <entry><para>Hypervisor</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>XenServer</para></entry>
- <entry><para>Name: systemvm-xenserver-4.2</para>
- <para>Description: systemvm-xenserver-4.2</para>
- <para>URL:http://download.cloud.com/templates/4.2/systemvmtemplate-2013-07-12-master-xen.vhd.bz2 </para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: XenServer</para>
- <para>Format: VHD</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- <row>
- <entry><para>KVM</para></entry>
- <entry><para>Name: systemvm-kvm-4.2</para>
- <para>Description: systemvm-kvm-4.2</para>
- <para>URL:
- http://download.cloud.com/templates/4.2/systemvmtemplate-2013-06-12-master-kvm.qcow2.bz2</para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: KVM</para>
- <para>Format: QCOW2</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- <row>
- <entry><para>VMware</para></entry>
- <entry><para>Name: systemvm-vmware-4.2</para>
- <para>Description: systemvm-vmware-4.2</para>
- <para>URL:
- http://download.cloud.com/templates/4.2/systemvmtemplate-4.2-vh7.ova</para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: VMware</para>
- <para>Format: OVA</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Most users of &PRODUCT; manage the installation and upgrades of &PRODUCT; with one
- of Linux's predominant package systems, RPM or APT. This guide assumes you'll be using
- RPM and Yum (for Red Hat Enterprise Linux or CentOS), or APT and Debian packages (for
- Ubuntu).</para>
- </listitem>
- <listitem>
- <para>Create RPM or Debian packages (as appropriate) and a repository from the 4.3 source,
- or check the Apache CloudStack downloads page at <ulink
- url="http://cloudstack.apache.org/downloads.html"
- >http://cloudstack.apache.org/downloads.html</ulink> for package repositories supplied
- by community members. You will need them for step <xref
- linkend="upgrade-deb-packages-4.3"/> or step <xref linkend="upgrade-rpm-packages-4.3"
- />.</para>
- <para>Instructions for creating packages from the &PRODUCT; source are in the <ulink
- url="http://cloudstack.apache.org/docs/en-US/index.html">Installation
- Guide</ulink>.</para>
- </listitem>
- <listitem>
- <para>Stop your management server or servers. Run this on all management server
- hosts:</para>
- <programlisting><prompt>#</prompt> service cloudstack-management stop</programlisting>
- </listitem>
- <listitem>
- <para>If you are running a usage server or usage servers, stop those as well:</para>
- <programlisting><prompt>#</prompt> service cloudstack-usage stop</programlisting>
- </listitem>
- <listitem>
- <para>Make a backup of your MySQL database. If you run into any issues or need to roll
- back the upgrade, this will assist in debugging or restoring your existing environment.
- You'll be prompted for your password.</para>
- <programlisting><prompt>#</prompt> mysqldump -u root -p cloud > cloudstack-backup.sql</programlisting>
- </listitem>
- <listitem>
- <para>Perform the following to verify the artifacts:</para>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>(optional) Install GPG keys if needed:</para>
- <programlisting>sudo apt-get install gpg</programlisting>
- </listitem>
- <listitem>
- <para>Import the GPG keys stored in the source distribution's KEYS file</para>
- <programlisting>gpg --import KEYS</programlisting>
- <para>Alternatively, download the signing keys, the IDs found in the KEYS file,
- individually by using a keyserver.</para>
- <para>For example:</para>
- <programlisting>gpg --recv-keys CC56CEA8</programlisting>
- </listitem>
- <listitem>
- <para>Verify signatures and hash files:</para>
- <programlisting>#gpg --verify apache-cloudstack-4.3-src.tar.bz2.asc
-#gpg --print-md MD5 apache-cloudstack-4.3-src.tar.bz2 | diff - apache-cloudstack-4.3-src.tar.bz2.md5
-#gpg --print-md SHA512 apache-cloudstack-4.3-src.tar.bz2 | diff - apache-cloudstack-4.3-src.tar.bz2.sha</programlisting>
- <para>Each of these commands should return no output. Any output from them implies
- that there is a difference between the hash you generated locally and the hash that
- has been pulled from the server.</para>
- </listitem>
- <listitem>
- <para>Get the commit hash from the VOTE email.</para>
- <para>For example: <code>4cd60f3d1683a3445c3248f48ae064fb573db2a1</code>. The value
- changes between releases.</para>
- </listitem>
- <listitem>
- <para>Create two new temporary directories:</para>
- <programlisting>#mkdir /tmp/cloudstack/git
-#mkdir /tmp/cloudstack/tree</programlisting>
- </listitem>
- <listitem>
- <para>Check out the 4.3 branch:</para>
- <programlisting>#git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git /tmp/cloudstack/git
-#cd /tmp/cloudstack/git
-#git archive --format=tar --prefix=/tmp/cloudstack/tree/ <commit-hash> | tar Pxf - </programlisting>
- </listitem>
- <listitem>
- <para>Unpack the release artifact:</para>
- <programlisting>#cd /tmp/cloudstack
-#tar xvfj apache-cloudstack-4.3-src.tar.bz2</programlisting>
- </listitem>
- <listitem>
- <para>Compare the contents of the release artifact with the contents pulled from the
- repo:</para>
- <programlisting>#diff -r /tmp/cloudstack/apache-cloudstack-4.3-src /tmp/cloudstack/tree</programlisting>
- <para>Ensure that content is the same.</para>
- </listitem>
- <listitem>
- <para>Verify the Code License Headers:</para>
- <programlisting>#cd /tmp/cloudstack/apache-cloudstack-4.3-src
-#mvn --projects='org.apache.cloudstack:cloudstack' org.apache.rat:apache-rat-plugin:0.8:check</programlisting>
- <para>The build fails if any non-compliant files are present that are not specifically
- excluded from the ASF license header requirement. You can optionally review the
- target/rat.txt file after the run completes. Passing the build implies that RAT
- certifies that the files are compliant and this test is passed.</para>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>(KVM Only) If primary storage of type local storage is in use, the path for this
- storage needs to be verified to ensure it passes new validation. Check local storage by
- querying the cloud.storage_pool table: </para>
- <programlisting><prompt>#</prompt>mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"</programlisting>
- <para>If local storage paths are found to have a trailing forward slash, remove it:
- <programlisting><prompt>#</prompt>mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';</programlisting>
- </para>
- </listitem>
- <listitem id="upgrade-deb-packages-4.3">
- <para>If you are using Ubuntu, follow this procedure to upgrade your packages. If not,
- skip to step <xref linkend="upgrade-rpm-packages-4.3"/>.</para>
- <note>
- <title>Community Packages</title>
- <para>This section assumes you're using the community supplied packages for &PRODUCT;.
- If you've created your own packages and APT repository, substitute your own URL for
- the ones used in these examples.</para>
- </note>
- <orderedlist id="debsteps-4.3" numeration="loweralpha">
- <listitem>
- <para>The first order of business will be to change the sources list for each system
- with &PRODUCT; packages. This means all management servers, and any hosts that have
- the KVM agent. (No changes should be necessary for hosts that are running VMware or
- Xen.)</para>
- <para>Start by opening <filename>/etc/apt/sources.list.d/cloudstack.list</filename> on
- any systems that have &PRODUCT; packages installed.</para>
- <para>This file should have one line, which contains:</para>
- <programlisting language="Bash">deb http://cloudstack.apt-get.eu/ubuntu precise 4.0</programlisting>
- <para>We'll change it to point to the new package repository:</para>
- <programlisting language="Bash">deb http://cloudstack.apt-get.eu/ubuntu precise 4.2</programlisting>
- <para>If you're using your own package repository, change this line to read as
- appropriate for your 4.3 repository.</para>
- </listitem>
- <listitem>
- <para>Now update your apt package list:</para>
- <programlisting language="Bash">$ sudo apt-get update</programlisting>
- </listitem>
- <listitem id="deb-master-4.3">
- <para>Now that you have the repository configured, it's time to install the
- <filename>cloudstack-management</filename> package. This will pull in any other
- dependencies you need.</para>
- <programlisting language="Bash">$ sudo apt-get install cloudstack-management</programlisting>
- </listitem>
- <listitem id="kvm-agent-deb-4.3">
- <para>You will need to manually install the <filename>cloudstack-agent</filename>
- package:</para>
- <programlisting language="Bash">$ sudo apt-get install cloudstack-agent</programlisting>
- <para>During the installation of <filename>cloudstack-agent</filename>, APT will copy
- your <filename>agent.properties</filename>, <filename>log4j-cloud.xml</filename>,
- and <filename>environment.properties</filename> from
- <filename>/etc/cloud/agent</filename> to
- <filename>/etc/cloudstack/agent</filename>.</para>
- <para>When prompted whether you wish to keep your configuration, say Yes.</para>
- </listitem>
- <listitem>
- <para>Verify that the file
- <filename>/etc/cloudstack/agent/environment.properties</filename> has a line that
- reads:</para>
- <programlisting language="Bash">paths.script=/usr/share/cloudstack-common</programlisting>
- <para>If not, add the line.</para>
- </listitem>
- <listitem>
- <para>Restart the agent:</para>
- <programlisting language="Bash">
-service cloudstack-agent stop
-killall jsvc
-service cloudstack-agent start
- </programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>(VMware only) Additional steps are required for each VMware cluster. These steps
- will not affect running guests in the cloud. These steps are required only for clouds
- using VMware clusters:</para>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>Stop the Management Server:</para>
- <programlisting>service cloudstack-management stop</programlisting>
- </listitem>
- <listitem>
- <para>Generate the encrypted equivalent of your vCenter password:</para>
- <programlisting>java -classpath /usr/share/cloudstack-common/lib/jasypt-1.9.0.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI encrypt.sh input="_your_vCenter_password_" password="`cat /etc/cloudstack/management/key`" verbose=false</programlisting>
- <para>Store the output from this step, we need to add this in cluster_details table
- and vmware_data_center tables in place of the plain text password</para>
- </listitem>
- <listitem>
- <para>Find the ID of the row of cluster_details table that you have to update:</para>
- <programlisting>mysql -u <username> -p<password></programlisting>
- <programlisting>select * from cloud.cluster_details;</programlisting>
- </listitem>
- <listitem>
- <para>Update the plain text password with the encrypted one</para>
- <programlisting>update cloud.cluster_details set value = '_ciphertext_from_step_1_' where id = _id_from_step_2_;</programlisting>
- </listitem>
- <listitem>
- <para>Confirm that the table is updated:</para>
- <programlisting>select * from cloud.cluster_details; </programlisting>
- </listitem>
- <listitem>
- <para>Find the ID of the correct row of vmware_data_center that you want to
- update</para>
- <programlisting>select * from cloud.vmware_data_center; </programlisting>
- </listitem>
- <listitem>
- <para>update the plain text password with the encrypted one:</para>
- <programlisting>update cloud.vmware_data_center set password = '_ciphertext_from_step_1_' where id = _id_from_step_5_; </programlisting>
- </listitem>
- <listitem>
- <para>Confirm that the table is updated:</para>
- <programlisting>select * from cloud.vmware_data_center; </programlisting>
- </listitem>
- <listitem>
- <para>Start the &PRODUCT; Management server </para>
- <programlisting>service cloudstack-management start</programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>(KVM only) Additional steps are required for each KVM host. These steps will not
- affect running guests in the cloud. These steps are required only for clouds using KVM
- as hosts and only on the KVM hosts.</para>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>Configure the CloudStack yum repository as detailed above.</para>
- </listitem>
- <listitem>
- <para>Stop the running agent.</para>
- <programlisting># service cloud-agent stop</programlisting>
- </listitem>
- <listitem>
- <para>Update the agent software.</para>
- <programlisting># yum update cloudstack-agent</programlisting>
- </listitem>
- <listitem>
- <para>Start the agent.</para>
- <programlisting># service cloudstack-agent start</programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem id="upgrade-rpm-packages-4.3">
- <para>If you are using CentOS or RHEL, follow this procedure to upgrade your packages. If
- not, skip to step <xref linkend="restart-system-vms-4.3"/>.</para>
- <note>
- <title>Community Packages</title>
- <para>This section assumes you're using the community supplied packages for &PRODUCT;.
- If you've created your own packages and yum repository, substitute your own URL for
- the ones used in these examples.</para>
- </note>
- <orderedlist id="rpmsteps-4.3" numeration="loweralpha">
- <listitem>
- <para>The first order of business will be to change the yum repository for each system
- with &PRODUCT; packages. This means all management servers, and any hosts that have
- the KVM agent. </para>
- <para>(No changes should be necessary for hosts that are running VMware or
- Xen.)</para>
- <para>Start by opening <filename>/etc/yum.repos.d/cloudstack.repo</filename> on any
- systems that have &PRODUCT; packages installed.</para>
- <para>This file should have content similar to the following:</para>
- <programlisting language="Bash">
-[apache-cloudstack]
-name=Apache CloudStack
-baseurl=http://cloudstack.apt-get.eu/rhel/4.0/
-enabled=1
-gpgcheck=0
- </programlisting>
- <para>If you are using the community provided package repository, change the base url
- to http://cloudstack.apt-get.eu/rhel/4.2/</para>
- <para>If you're using your own package repository, change this line to read as
- appropriate for your 4.3 repository.</para>
- </listitem>
- <listitem id="rpm-master-4.3">
- <para>Now that you have the repository configured, it's time to install the
- <filename>cloudstack-management</filename> package by upgrading the older
- <filename>cloudstack-management</filename> package.</para>
- <programlisting language="Bash">$ sudo yum upgrade cloudstack-management</programlisting>
- </listitem>
- <listitem id="kvm-agent-rpm-4.3">
- <para>For KVM hosts, you will need to upgrade the <filename>cloud-agent</filename>
- package, similarly installing the new version as
- <filename>cloudstack-agent</filename>.</para>
- <programlisting language="Bash">$ sudo yum upgrade cloudstack-agent</programlisting>
- </listitem>
- <listitem>
- <para>Verify that the file
- <filename>/etc/cloudstack/agent/environment.properties</filename> has a line that
- reads:</para>
- <programlisting language="Bash">paths.script=/usr/share/cloudstack-common</programlisting>
- <para>If not, add the line.</para>
- </listitem>
- <listitem>
- <para>Restart the agent:</para>
- <programlisting language="Bash">
-service cloudstack-agent stop
-killall jsvc
-service cloudstack-agent start
- </programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem id="restart-mgmt-server-4.3">
- <para>Now it's time to restart the management server</para>
- <programlisting language="Bash"><prompt>#</prompt> service cloudstack-management start</programlisting>
- </listitem>
- <listitem id="restart-system-vms-4.3">
- <para>Once you've upgraded the packages on your management servers, you'll need to restart
- the system VMs. Ensure that the admin port is set to 8096 by using the
- "integration.api.port" global parameter. This port is used by the cloud-sysvmadm script
- at the end of the upgrade procedure. For information about how to set this parameter,
- see "Setting Global Configuration Parameters" in the Installation Guide. Changing this
- parameter will require management server restart. Also make sure port 8096 is open in
- your local host firewall to do this. </para>
- <para>There is a script that will do this for you, all you need to do is run the script
- and supply the IP address for your MySQL instance and your MySQL credentials:</para>
- <programlisting language="Bash"><prompt>#</prompt> nohup cloudstack-sysvmadm -d <replaceable>IP address</replaceable> -u cloud -p -a > sysvm.log 2>&1 &</programlisting>
- <para>You can monitor the log for progress. The process of restarting the system VMs can
- take an hour or more.</para>
- <programlisting language="Bash"><prompt>#</prompt> tail -f sysvm.log</programlisting>
- <para>The output to <filename>sysvm.log</filename> will look something like this:</para>
- <programlisting language="Bash">
-Stopping and starting 1 secondary storage vm(s)...
-Done stopping and starting secondary storage vm(s)
-Stopping and starting 1 console proxy vm(s)...
-Done stopping and starting console proxy vm(s).
-Stopping and starting 4 running routing vm(s)...
-Done restarting router(s).
- </programlisting>
- </listitem>
- <listitem>
- <note>
- <title>For Xen Hosts: Copy vhd-utils</title>
- <para>This step is only for CloudStack installs that are using Xen hosts.</para>
- </note>
- <para>Copy the file <filename>vhd-utils</filename> to
- <filename>/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver</filename>.</para>
- </listitem>
- </orderedlist>
- </section>
- <section id="upgrade-from-4.1-to-4.3">
- <title>Upgrade from 4.1.x to 4.3</title>
- <para>This section will guide you from &PRODUCT; 4.1.x versions to &PRODUCT; 4.3.</para>
- <para>Any steps that are hypervisor-specific will be called out with a note.</para>
- <para>We recommend reading through this section once or twice before beginning your upgrade
- procedure, and working through it on a test system before working on a production
- system.</para>
- <orderedlist>
- <listitem>
- <para>Most users of &PRODUCT; manage the installation and upgrades of &PRODUCT; with one
- of Linux's predominant package systems, RPM or APT. This guide assumes you'll be using
- RPM and Yum (for Red Hat Enterprise Linux or CentOS), or APT and Debian packages (for
- Ubuntu).</para>
- </listitem>
- <listitem>
- <note>
- <para>The following upgrade instructions should be performed regardless of hypervisor
- type.</para>
- </note>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>While running the existing 4.1.x system, log in to the UI as root
- administrator.</para>
- </listitem>
- <listitem>
- <para>In the left navigation bar, click Templates.</para>
- </listitem>
- <listitem>
- <para>In Select view, click Templates.</para>
- </listitem>
- <listitem>
- <para>Click Register template.</para>
- <para>The Register template dialog box is displayed.</para>
- </listitem>
- <listitem>
- <para>In the Register template dialog box, specify the following values (do not change
- these):</para>
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="1">
- <colspec colwidth="1*" colname="1" colnum="1"/>
- <colspec colwidth="2*" colname="2" colnum="2"/>
- <thead>
- <row>
- <entry><para>Hypervisor</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>XenServer</para></entry>
- <entry><para>Name: systemvm-xenserver-4.3</para>
- <para>Description: systemvm-xenserver-4.3</para>
- <para>URL:http://download.cloud.com/templates/4.3/systemvmtemplate-2014-07-12-master-xen.vhd.bz2 </para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: XenServer</para>
- <para>Format: VHD</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- <row>
- <entry><para>KVM</para></entry>
- <entry><para>Name: systemvm-kvm-4.3</para>
- <para>Description: systemvm-kvm-4.3</para>
- <para>URL:
- http://download.cloud.com/templates/4.3/systemvmtemplate-2014-06-12-master-kvm.qcow2.bz2</para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: KVM</para>
- <para>Format: QCOW2</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- <row>
- <entry><para>VMware</para></entry>
- <entry><para>Name: systemvm-vmware-4.3</para>
- <para>Description: systemvm-vmware-4.3</para>
- <para>URL:
- http://download.cloud.com/templates/4.3/systemvmtemplate-4.3-vh7.ova</para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: VMware</para>
- <para>Format: OVA</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Create RPM or Debian packages (as appropriate) and a repository from the 4.2.1
- source, or check the Apache CloudStack downloads page at <ulink
- url="http://cloudstack.apache.org/downloads.html"
- >http://cloudstack.apache.org/downloads.html</ulink> for package repositories supplied
- by community members. You will need them for step <xref
- linkend="upgrade-deb-packages-41to42"/> or step <xref
- linkend="upgrade-rpm-packages-41to42"/>.</para>
- <para>Instructions for creating packages from the &PRODUCT; source are in the <ulink
- url="http://cloudstack.apache.org/docs/en-US/index.html">Installation
- Guide</ulink>.</para>
- </listitem>
- <listitem>
- <para>Stop your management server or servers. Run this on all management server
- hosts:</para>
- <programlisting><prompt>#</prompt> service cloudstack-management stop</programlisting>
- </listitem>
- <listitem>
- <para>If you are running a usage server or usage servers, stop those as well:</para>
- <programlisting><prompt>#</prompt> service cloudstack-usage stop</programlisting>
- </listitem>
- <listitem>
- <para>Make a backup of your MySQL database. If you run into any issues or need to roll
- back the upgrade, this will assist in debugging or restoring your existing environment.
- You'll be prompted for your password.</para>
- <programlisting><prompt>#</prompt> mysqldump -u root -p cloud > cloudstack-backup.sql</programlisting>
- </listitem>
- <listitem>
- <para>(KVM Only) If primary storage of type local storage is in use, the path for this
- storage needs to be verified to ensure it passes new validation. Check local storage by
- querying the cloud.storage_pool table: </para>
- <programlisting><prompt>#</prompt>mysql -u cloud -p -e "select id,name,path from cloud.storage_pool where pool_type='Filesystem'"</programlisting>
- <para>If local storage paths are found to have a trailing forward slash, remove it:
- <programlisting><prompt>#</prompt>mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';</programlisting>
- </para>
- </listitem>
- <listitem id="upgrade-deb-packages-41to42">
- <para>If you are using Ubuntu, follow this procedure to upgrade your packages. If not,
- skip to step <xref linkend="upgrade-rpm-packages-41to42"/>.</para>
- <note>
- <title>Community Packages</title>
- <para>This section assumes you're using the community supplied packages for &PRODUCT;.
- If you've created your own packages and APT repository, substitute your own URL for
- the ones used in these examples.</para>
- </note>
- <orderedlist id="debsteps-41to42" numeration="loweralpha">
- <listitem>
- <para>The first order of business will be to change the sources list for each system
- with &PRODUCT; packages. This means all management servers, and any hosts that have
- the KVM agent. (No changes should be necessary for hosts that are running VMware or
- Xen.)</para>
- <para>Start by opening <filename>/etc/apt/sources.list.d/cloudstack.list</filename> on
- any systems that have &PRODUCT; packages installed.</para>
- <para>This file should have one line, which contains:</para>
- <programlisting language="Bash">deb http://cloudstack.apt-get.eu/ubuntu precise 4.0</programlisting>
- <para>We'll change it to point to the new package repository:</para>
- <programlisting language="Bash">deb http://cloudstack.apt-get.eu/ubuntu precise 4.2</programlisting>
- <para>If you're using your own package repository, change this line to read as
- appropriate for your 4.3 repository.</para>
- </listitem>
- <listitem>
- <para>Now update your apt package list:</para>
- <programlisting language="Bash">$ sudo apt-get update</programlisting>
- </listitem>
- <listitem id="deb-master-41to42">
- <para>Now that you have the repository configured, it's time to install the
- <filename>cloudstack-management</filename> package. This will pull in any other
- dependencies you need.</para>
- <programlisting language="Bash">$ sudo apt-get install cloudstack-management</programlisting>
- </listitem>
- <listitem id="kvm-agent-deb-41to42">
- <para>You will need to manually install the <filename>cloudstack-agent</filename>
- package:</para>
- <programlisting language="Bash">$ sudo apt-get install cloudstack-agent</programlisting>
- <para>During the installation of <filename>cloudstack-agent</filename>, APT will copy
- your <filename>agent.properties</filename>, <filename>log4j-cloud.xml</filename>,
- and <filename>environment.properties</filename> from
- <filename>/etc/cloud/agent</filename> to
- <filename>/etc/cloudstack/agent</filename>.</para>
- <para>When prompted whether you wish to keep your configuration, say Yes.</para>
- </listitem>
- <listitem>
- <para>Verify that the file
- <filename>/etc/cloudstack/agent/environment.properties</filename> has a line that
- reads:</para>
- <programlisting language="Bash">paths.script=/usr/share/cloudstack-common</programlisting>
- <para>If not, add the line.</para>
- </listitem>
- <listitem>
- <para>Restart the agent:</para>
- <programlisting language="Bash">
-service cloudstack-agent stop
-killall jsvc
-service cloudstack-agent start
- </programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>(VMware only) Additional steps are required for each VMware cluster. These steps
- will not affect running guests in the cloud. These steps are required only for clouds
- using VMware clusters:</para>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>Stop the Management Server:</para>
- <programlisting>service cloudstack-management stop</programlisting>
- </listitem>
- <listitem>
- <para>Generate the encrypted equivalent of your vCenter password:</para>
- <programlisting>java -classpath /usr/share/cloudstack-common/lib/jasypt-1.9.0.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI encrypt.sh input="_your_vCenter_password_" password="`cat /etc/cloudstack/management/key`" verbose=false</programlisting>
- <para>Store the output from this step, we need to add this in cluster_details table
- and vmware_data_center tables in place of the plain text password</para>
- </listitem>
- <listitem>
- <para>Find the ID of the row of cluster_details table that you have to update:</para>
- <programlisting>mysql -u <username> -p<password></programlisting>
- <programlisting>select * from cloud.cluster_details;</programlisting>
- </listitem>
- <listitem>
- <para>Update the plain text password with the encrypted one</para>
- <programlisting>update cloud.cluster_details set value = '_ciphertext_from_step_1_' where id = _id_from_step_2_;</programlisting>
- </listitem>
- <listitem>
- <para>Confirm that the table is updated:</para>
- <programlisting>select * from cloud.cluster_details; </programlisting>
- </listitem>
- <listitem>
- <para>Find the ID of the correct row of vmware_data_center that you want to
- update</para>
- <programlisting>select * from cloud.vmware_data_center; </programlisting>
- </listitem>
- <listitem>
- <para>update the plain text password with the encrypted one:</para>
- <programlisting>update cloud.vmware_data_center set password = '_ciphertext_from_step_1_' where id = _id_from_step_5_; </programlisting>
- </listitem>
- <listitem>
- <para>Confirm that the table is updated:</para>
- <programlisting>select * from cloud.vmware_data_center; </programlisting>
- </listitem>
- <listitem>
- <para>Start the &PRODUCT; Management server </para>
- <programlisting>service cloudstack-management start</programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>(KVM only) Additional steps are required for each KVM host. These steps will not
- affect running guests in the cloud. These steps are required only for clouds using KVM
- as hosts and only on the KVM hosts.</para>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>Configure the CloudStack yum repository as detailed above.</para>
- </listitem>
- <listitem>
- <para>Stop the running agent.</para>
- <programlisting># service cloud-agent stop</programlisting>
- </listitem>
- <listitem>
- <para>Update the agent software.</para>
- <programlisting># yum update cloudstack-agent</programlisting>
- </listitem>
- <listitem>
- <para>Start the agent.</para>
- <programlisting># service cloudstack-agent start</programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem id="upgrade-rpm-packages-41to42">
- <para>If you are using CentOS or RHEL, follow this procedure to upgrade your packages. If
- not, skip to step <xref linkend="restart-system-vms-41to42"/>.</para>
- <note>
- <title>Community Packages</title>
- <para>This section assumes you're using the community supplied packages for &PRODUCT;.
- If you've created your own packages and yum repository, substitute your own URL for
- the ones used in these examples.</para>
- </note>
- <orderedlist id="rpmsteps-41to42" numeration="loweralpha">
- <listitem>
- <para>The first order of business will be to change the yum repository for each system
- with &PRODUCT; packages. This means all management servers, and any hosts that have
- the KVM agent. </para>
- <para>(No changes should be necessary for hosts that are running VMware or
- Xen.)</para>
- <para>Start by opening <filename>/etc/yum.repos.d/cloudstack.repo</filename> on any
- systems that have &PRODUCT; packages installed.</para>
- <para>This file should have content similar to the following:</para>
- <programlisting language="Bash">
-[apache-cloudstack]
-name=Apache CloudStack
-baseurl=http://cloudstack.apt-get.eu/rhel/4.0/
-enabled=1
-gpgcheck=0
- </programlisting>
- <para>If you are using the community provided package repository, change the base url
- to http://cloudstack.apt-get.eu/rhel/4.2/</para>
- <para>If you're using your own package repository, change this line to read as
- appropriate for your 4.3 repository.</para>
- </listitem>
- <listitem id="rpm-master-41to42">
- <para>Now that you have the repository configured, it's time to install the
- <filename>cloudstack-management</filename> package by upgrading the older
- <filename>cloudstack-management</filename> package.</para>
- <programlisting language="Bash">$ sudo yum upgrade cloudstack-management</programlisting>
- </listitem>
- <listitem id="kvm-agent-rpm-41to42">
- <para>For KVM hosts, you will need to upgrade the <filename>cloud-agent</filename>
- package, similarly installing the new version as
- <filename>cloudstack-agent</filename>.</para>
- <programlisting language="Bash">$ sudo yum upgrade cloudstack-agent</programlisting>
- </listitem>
- <listitem>
- <para>Verify that the file
- <filename>/etc/cloudstack/agent/environment.properties</filename> has a line that
- reads:</para>
- <programlisting language="Bash">paths.script=/usr/share/cloudstack-common</programlisting>
- <para>If not, add the line.</para>
- </listitem>
- <listitem>
- <para>Restart the agent:</para>
- <programlisting language="Bash">
-service cloudstack-agent stop
-killall jsvc
-service cloudstack-agent start
- </programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem id="restart-mgmt-server-41to42">
- <para>Now it's time to restart the management server</para>
- <programlisting language="Bash"><prompt>#</prompt> service cloudstack-management start</programlisting>
- </listitem>
- <listitem id="restart-system-vms-41to42">
- <para>Once you've upgraded the packages on your management servers, you'll need to restart
- the system VMs. Ensure that the admin port is set to 8096 by using the
- "integration.api.port" global parameter. This port is used by the cloud-sysvmadm script
- at the end of the upgrade procedure. For information about how to set this parameter,
- see "Setting Global Configuration Parameters" in the Installation Guide. Changing this
- parameter will require management server restart. Also make sure port 8096 is open in
- your local host firewall to do this. </para>
- <para>There is a script that will do this for you, all you need to do is run the script
- and supply the IP address for your MySQL instance and your MySQL credentials:</para>
- <programlisting language="Bash"><prompt>#</prompt> nohup cloudstack-sysvmadm -d <replaceable>IP address</replaceable> -u cloud -p -a > sysvm.log 2>&1 &</programlisting>
- <para>You can monitor the log for progress. The process of restarting the system VMs can
- take an hour or more.</para>
- <programlisting language="Bash"><prompt>#</prompt> tail -f sysvm.log</programlisting>
- <para>The output to <filename>sysvm.log</filename> will look something like this:</para>
- <programlisting language="Bash">
-Stopping and starting 1 secondary storage vm(s)...
-Done stopping and starting secondary storage vm(s)
-Stopping and starting 1 console proxy vm(s)...
-Done stopping and starting console proxy vm(s).
-Stopping and starting 4 running routing vm(s)...
-Done restarting router(s).
- </programlisting>
- </listitem>
- <listitem>
- <note>
- <title>For Xen Hosts: Copy vhd-utils</title>
- <para>This step is only for CloudStack installs that are using Xen hosts.</para>
- </note>
- <para>Copy the file <filename>vhd-utils</filename> to
- <filename>/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver</filename>.</para>
- </listitem>
- </orderedlist>
- </section>
- <section id="upgrade-from-4.0-to-4.3">
- <title>Upgrade from 4.0.x to 4.3</title>
- <para>This section will guide you from &PRODUCT; 4.0.x versions to &PRODUCT; 4.3.</para>
- <para>Any steps that are hypervisor-specific will be called out with a note.</para>
- <warning>
- <title>Package Structure Changes</title>
- <para>The package structure for &PRODUCT; has changed significantly since the 4.0.x
- releases. If you've compiled your own packages, you'll notice that the package names and
- the number of packages has changed. This is <emphasis>not</emphasis> a bug.</para>
- <para>However, this <emphasis>does</emphasis> mean that the procedure is not as simple as an
- <command>apt-get upgrade</command> or <command>yum update</command>, so please follow
- this section carefully.</para>
- </warning>
- <para>We recommend reading through this section once or twice before beginning your upgrade
- procedure, and working through it on a test system before working on a production
- system.</para>
- <orderedlist>
- <listitem>
- <para>Most users of &PRODUCT; manage the installation and upgrades of &PRODUCT; with one
- of Linux's predominant package systems, RPM or APT. This guide assumes you'll be using
- RPM and Yum (for Red Hat Enterprise Linux or CentOS), or APT and Debian packages (for
- Ubuntu).</para>
- <para>Create RPM or Debian packages (as appropriate) and a repository from the 4.1.0
- source, or check the Apache CloudStack downloads page at <ulink
- url="http://cloudstack.apache.org/downloads.html"
- >http://cloudstack.apache.org/downloads.html</ulink> for package repositories supplied
- by community members. You will need them for step <xref
- linkend="upgrade-deb-packages-40to41"/> or step <xref
- linkend="upgrade-rpm-packages-40to41"/>.</para>
- <para>Instructions for creating packages from the &PRODUCT; source are in the <ulink
- url="http://cloudstack.apache.org/docs/en-US/index.html">Installation
- Guide</ulink>.</para>
- </listitem>
- <listitem>
- <note>
- <para>The following upgrade instructions should be performed regardless of hypervisor
- type.</para>
- </note>
- <orderedlist numeration="loweralpha">
- <listitem>
- <para>While running the existing 4.0.0 system, log in to the UI as root
- administrator.</para>
- </listitem>
- <listitem>
- <para>In the left navigation bar, click Templates.</para>
- </listitem>
- <listitem>
- <para>In Select view, click Templates.</para>
- </listitem>
- <listitem>
- <para>Click Register template.</para>
- <para>The Register template dialog box is displayed.</para>
- </listitem>
- <listitem>
- <para>In the Register template dialog box, specify the following values (do not change
- these):</para>
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="1">
- <colspec colwidth="1*" colname="1" colnum="1"/>
- <colspec colwidth="2*" colname="2" colnum="2"/>
- <thead>
- <row>
- <entry><para>Hypervisor</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>XenServer</para></entry>
- <entry><para>Name: systemvm-xenserver-4.3</para>
- <para>Description: systemvm-xenserver-4.3</para>
- <para>URL:http://download.cloud.com/templates/4.3/systemvmtemplate-2013-07-12-master-xen.vhd.bz2 </para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: XenServer</para>
- <para>Format: VHD</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- <row>
- <entry><para>KVM</para></entry>
- <entry><para>Name: systemvm-kvm-4.3</para>
- <para>Description: systemvm-kvm-4.3</para>
- <para>URL:
- http://download.cloud.com/templates/4.3/systemvmtemplate-2013-06-12-master-kvm.qcow2.bz2</para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: KVM</para>
- <para>Format: QCOW2</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- <row>
- <entry><para>VMware</para></entry>
- <entry><para>Name: systemvm-vmware-4.3</para>
- <para>Description: systemvm-vmware-4.3</para>
- <para>URL:
- http://download.cloud.com/templates/4.3/systemvmtemplate-4.2-vh7.ova</para>
- <para>Zone: Choose the zone where this hypervisor is used</para>
- <para>Hypervisor: VMware</para>
- <para>Format: OVA</para>
- <para>OS Type: Debian GNU/Linux 7.0 (32-bit) (or the highest Debian release
- number available in the dropdown)</para>
- <para>Extractable: no</para>
- <para>Password Enabled: no</para>
- <para>Public: no</para>
- <para>Featured: no</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Stop your management server or servers. Run this on all management server
- hosts:</para>
- <programlisting><prompt>#</prompt> service cloud-management stop</programlisting>
- </listitem>
- <listitem>
- <para>If you are running a usage server or usage servers, stop those as well:</para>
- <programlisting><prompt>#</prompt> service cloud-usage stop</programlisting>
- </listitem>
- <listitem>
- <para>Make a backup of your MySQL database. If you run into any issues or need to roll
- back the upgrade, this will assist in debugging or restoring your existing environment.
- You'll be prompted for your password.</para>
- <programlisting><prompt>#</prompt> mysqldump -u root -p cloud > cloudstack-backup.sql</programlisting>
- </listitem>
- <listitem>
- <para>Whether you're upgrading a Red Hat/CentOS based system or Ubuntu based system,
- you're going to need to stop the CloudStack management server before proceeding.</para>
- <programlisting language="Bash"><prompt>#</prompt> service cloud-management stop</programlisting>
- </listitem>
- <listitem>
- <para>If you have made changes to
- <filename>/etc/cloud/management/components.xml</filename>, you'll need to carry these
- over manually to the new file,
- <filename>/etc/cloudstack/management/componentContext.xml</filename>. This is not done
- automatically. (If you're unsure, we recommend making a backup of the original
- <filename>components.xml</filename> to be on the safe side.</para>
- </listitem>
- <listitem>
- <para>After upgrading to 4.3, API clients are expected to send plain text passwords for
- login and user creation, instead of MD5 hash. Incase, api client changes are not
- acceptable, following changes are to be made for backward compatibility:</para>
- <para>Modify componentsContext.xml, and make PlainTextUserAuthenticator as the default
- authenticator (1st entry in the userAuthenticators adapter list is default)</para>
- <programlisting language="XML">
-<!-- Security adapters -->
-<bean id="userAuthenticators" class="com.cloud.utils.component.AdapterList">
- <property name="Adapters">
- <list>
- <ref bean="PlainTextUserAuthenticator"/>
- <ref bean="MD5UserAuthenticator"/>
- <ref bean="LDAPUserAuthenticator"/>
- </list>
- </property>
-</bean>
- </programlisting>
- <para>PlainTextUserAuthenticator works the same way MD5UserAuthenticator worked prior to
- 4.3.</para>
- </listitem>
- <listitem id="upgrade-deb-packages-40to41">
- <para>If you are using Ubuntu, follow this procedure to upgrade your packages. If not,
- skip to step <xref linkend="upgrade-rpm-packages-40to41"/>.</para>
- <note>
- <title>Community Packages</title>
- <para>This section assumes you're using the community supplied packages for &PRODUCT;.
- If you've created your own packages and APT repository, substitute your own URL for
- the ones used in these examples.</para>
- </note>
- <orderedlist id="debsteps-40to41">
- <listitem>
- <para>The first order of business will be to change the sources list for each system
- with &PRODUCT; packages. This means all management servers, and any hosts that have
- the KVM agent. (No changes should be necessary for hosts that are running VMware or
- Xen.)</para>
- <para>Start by opening <filename>/etc/apt/sources.list.d/cloudstack.list</filename> on
- any systems that have &PRODUCT; packages installed.</para>
-
<TRUNCATED>