Google Git
Sign in
apache / cloudstack-docs / ef9c1de5f8bc1d3d44e7cee610e0e8b9c5a01628 / . / release-notes / en-US / Release_Notes.xml
blob: a51657f3648d0973b5fc5cd79b95f825b872e702 [file] [log] [blame]
<?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.2.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.2.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.2">
<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="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 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 so that alerts are generated and published though the following
services run on a separate host:</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>
</section>
</section>
<section id="issues-fixed-4.3">
<title>Issues Fixed in 4.3</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>This section includes a summary of known issues were fixed in 4.3. .</para>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth="1.0*" colname="1" colnum="1"/>
<colspec colwidth="6.19*" colname="2" colnum="2"/>
<thead>
<row>
<entry>
<para>Defect</para>
</entry>
<entry>
<para>Description</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry><para>CLOUDSTACK-2562</para></entry>
<entry><para>When a virtual router on a VMware ESX is restarted out of band by VMware
HA, &PRODUCT; does not re-program the port forwarding, NAT, and load balancer
rules. </para></entry>
</row>
<row>
<entry><para>CLOUDSTACK-3154</para></entry>
<entry><para>When deleting the VMware DataCenter from the Zone the DataCenter gets
deleted but UI screen stays in processing state.</para></entry>
</row>
<row>
<entry><para>CLOUDSTACK-3252</para></entry>
<entry><para>An instance deployed by using explicit or implicit dedication doesn't
generate a usage event.</para></entry>
</row>
<row>
<entry><para>CLOUDSTACK-4861</para></entry>
<entry><para>Selection of physical network to implement guest network is now work as
expected if guest traffic spans across multiple physical networks.</para></entry>
</row>
<row>
<entry><para>CLOUDSTACK-5145</para></entry>
<entry><para>The ListNetworkACL API lists the ACLs owned only by the
user.</para></entry>
</row>
<row>
<entry>
<para/>
</entry>
<entry>
<para>.</para>
</entry>
</row>
<row>
<entry>
<para/>
</entry>
<entry>
<para/>
</entry>
</row>
<row>
<entry>
<para/>
</entry>
<entry>
<para/>
</entry>
</row>
<row>
<entry>
<para/>
</entry>
<entry>
<para/>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="known-issues-4.3">
<title>Known Issues in 4.3</title>
<para>This section includes a summary of known issues in 4.3.</para>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth="1.0*" colname="1" colnum="1"/>
<colspec colwidth="5.69*" colname="2" colnum="2"/>
<thead>
<row>
<entry>
<para>Issue ID</para>
</entry>
<entry>
<para>Description</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>CLOUDSTACK-4875</para>
</entry>
<entry>
<para>[VMware] vCenter 5.5 - SYSTEM VM: Unable to create deployment for VM</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5159</para>
</entry>
<entry>
<para>[VMware] Reset SSH keypair randomly fails.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5188</para>
</entry>
<entry>
<para>Password reset of vm on XenServer and VMware does not work on first
reboot.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-2140</para>
</entry>
<entry>
<para>Host is still marked as being in UP state when the host is shutdown and there
are no more hosts in the cluster.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4545</para>
</entry>
<entry>
<para>[VMware] Master template used by linked clones should not be available for
deletion.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4577</para>
</entry>
<entry>
<para>[VMware] Unexpected exception while executing
org.apache.cloudstack.api.command.user.volume.ResizeVolumeCmd
java.lang.NullPointerException.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4587</para>
</entry>
<entry>
<para>VM is failing to deploy on a Legacy zone after adding zone wide primary
storage and moving cluster wide primary storage to maintenance mode.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4594</para>
</entry>
<entry>
<para>[VMware] [Upgrade] Failed to revert VM Snapshot which were created before Live
Storage Migrating the VM to other clusters.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4616</para>
</entry>
<entry>
<para>When system VMs fail to start when host is down, link local IP addresses do
not get released resulting in all the link local IPs being consumed
eventually.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5008</para>
</entry>
<entry>
<para>[VMware] Failed to start the VM after performing Cold Migration of Volume to
Second Zone wide primary Storage.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5014</para>
</entry>
<entry>
<para>[VMware] DeployVM with data disk failed with exception.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5054</para>
</entry>
<entry>
<para>VM migration involving storage migration on vmware fails with the 'The object
has already been deleted or has not been completely created' exception.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5119</para>
</entry>
<entry>
<para>VLAN provisioning broken in F5</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4475</para>
</entry>
<entry>
<para>Attaching an uploaded volume to a VM is always going to first primary storage
added.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4492</para>
</entry>
<entry>
<para>Attaching volume to a VM fails after upgrade if the volume was uploaded before
upgrade. </para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4496</para>
</entry>
<entry>
<para>[VMware] System VMs are failed to start with NPE when host is in maintenance
state.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4504</para>
</entry>
<entry>
<para>VM creation is failing using the Ubuntu ISO with XenServer 6.1 and 6.2</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4536</para>
</entry>
<entry>
<para>Inconsistency in volume store location on secondary storage for uploaded and
extracted volume.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4574</para>
</entry>
<entry>
<para>NPE while executing DestroyVM command.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4593</para>
</entry>
<entry>
<para>[VMware] [Upgrade] Livestorage Migration and VM Snapshot features are not
fully functional after upgrade.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4620</para>
</entry>
<entry>
<para>VM failed to start on the host on which it was running due to not having
enough reserved memory when the host was powered on after being shutdown.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4638</para>
</entry>
<entry>
<para>State information is not synced on Starting VM directly via vCenter.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4639</para>
</entry>
<entry>
<para>Status of VM is not synced properly when host is HA during hypervisor
failure.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4657</para>
</entry>
<entry>
<para>[CEPH] Attaching a volume to an instance that is migrated from one primary to
another primary fails.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4697</para>
</entry>
<entry>
<para>Not able to delete Primary storage when there are no hosts in the
cluster.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4734</para>
</entry>
<entry>
<para>Creating snapshot from ROOT volume fails with the Failed to create snapshot
due to an internal error creating snapshot for volume 14 error message.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4743</para>
</entry>
<entry>
<para>The applyStaticRoutes/createPrivateGatway/deletePrivateGateway APIs read from
the vpc_service_map table instead of relying on hard-coded values.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4789</para>
</entry>
<entry>
<para>Fix ResourceMetaDataManagerTest.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4850</para>
</entry>
<entry>
<para>[UCS] using template instead of cloning profile.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4861</para>
</entry>
<entry>
<para>[VMware] If Guest traffic spans across multiple physical networks, selection
of physical network to implement guest network is not working correctly.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4906</para>
</entry>
<entry>
<para>Add network address to the Marvin dependency list.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-4978</para>
</entry>
<entry>
<para>[VMware] Provisioning VMs from templates fails with the ROOT-249/ROOT-249.vmdk
not found error</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5002</para>
</entry>
<entry>
<para>Destroying VM does not work. VM destroy failed with the Stop i-2-59-VM command
due to invalid object reference. The object may have recently been deleted.
</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5005</para>
</entry>
<entry>
<para>Stopping multiple VMs does not work.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5020</para>
</entry>
<entry>
<para>Recreate system VM fails in a specific scenario during storage
maintenance.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5075</para>
</entry>
<entry>
<para>Various issues with destroying a VM with local storage. VM disk statistics
cannot be updated for a VM.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5090</para>
</entry>
<entry>
<para>Anti-Affinity: VM fails to start on a cluster belonging to a different
pod.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5098</para>
</entry>
<entry>
<para>[VMware] Entries in <code>vmware_data_center</code> and
<code>vmware_data_center_zone_map</code> are not cleaned up when there is a
failure to add the cluster.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5118</para>
</entry>
<entry>
<para>Virtual Routers are listed multiple times in the Infrastructure page.</para>
</entry>
</row>
<row>
<entry>
<para>CLOUDSTACK-5123</para>
</entry>
<entry>
<para>[VMware] Memory over-provisioning behaviour.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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 &gt; 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/ &lt;commit-hash&gt; | 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 &lt;username&gt; -p&lt;password&gt;</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 &gt; sysvm.log 2&gt;&amp;1 &amp;</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.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>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 &gt; 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 &lt;username&gt; -p&lt;password&gt;</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 &gt; sysvm.log 2&gt;&amp;1 &amp;</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.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>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 &gt; 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">
&lt;!-- Security adapters --&gt;
&lt;bean id="userAuthenticators" class="com.cloud.utils.component.AdapterList"&gt;
&lt;property name="Adapters"&gt;
&lt;list&gt;
&lt;ref bean="PlainTextUserAuthenticator"/&gt;
&lt;ref bean="MD5UserAuthenticator"/&gt;
&lt;ref bean="LDAPUserAuthenticator"/&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/bean&gt;
</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>
<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.1</programlisting>
<para>If you're using your own package repository, change this line to read as
appropriate for your 4.1.0 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-40to41">
<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-40to41">
<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 cloud-agent stop
killall jsvc
service cloudstack-agent start
</programlisting>
</listitem>
<listitem>
<para>During the upgrade, <filename>log4j-cloud.xml</filename> was simply copied over,
so the logs will continue to be added to
<filename>/var/log/cloud/agent/agent.log</filename>. There's nothing
<emphasis>wrong</emphasis> with this, but if you prefer to be consistent, you can
change this by copying over the sample configuration file:</para>
<programlisting language="Bash">
cd /etc/cloudstack/agent
mv log4j-cloud.xml.dpkg-dist log4j-cloud.xml
service cloudstack-agent restart
</programlisting>
</listitem>
<listitem>
<para>Once the agent is running, you can uninstall the old cloud-* packages from your
system:</para>
<programlisting language="Bash">sudo dpkg --purge cloud-agent</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem id="upgrade-rpm-packages-40to41">
<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-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 yum repository, substitute your own URL for
the ones used in these examples.</para>
</note>
<orderedlist id="rpmsteps-40to41">
<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. (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 baseurl
to http://cloudstack.apt-get.eu/rhel/4.1/</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-40to41">
<para>Now that you have the repository configured, it's time to install the
<filename>cloudstack-management</filename> package by upgrading the older
<filename>cloud-client</filename> package.</para>
<programlisting language="Bash">$ sudo yum upgrade cloud-client</programlisting>
</listitem>
<listitem id="kvm-agent-rpm-40to41">
<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 cloud-agent</programlisting>
<para>During the installation of <filename>cloudstack-agent</filename>, the RPM 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>
</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 cloud-agent stop
killall jsvc
service cloudstack-agent start
</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem id="restart-system-vms-40to41">
<para>Once you've upgraded the packages on your management servers, you'll need to restart
the system VMs. 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 &gt; sysvm.log 2&gt;&amp;1 &amp;</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-3.0.x-to-4.3">
<title>Upgrade from 3.0.x to 4.3</title>
<para>This section will guide you from Citrix CloudStack 3.0.x to Apache CloudStack 4.3.
Sections that are hypervisor-specific will be called out with a note.</para>
<orderedlist>
<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 3.0.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.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>
<listitem>
<para>Watch the screen to be sure that the template downloads successfully and enters
the READY state. Do not proceed until this is successful.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>(KVM on RHEL 6.0/6.1 only) If your existing &PRODUCT; deployment includes one or
more clusters of KVM hosts running RHEL 6.0 or RHEL 6.1, perform the following:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Ensure that you upgrade the operating system version on those hosts before
upgrading &PRODUCT;</para>
<para>To do that, change the yum repository for each system with &PRODUCT; packages,
that implies that all the Management Servers and any hosts that have the KVM agent.
</para>
</listitem>
<listitem>
<para>Open <filename>/etc/yum.repos.d/cloudstack.repo</filename> on any systems that
have &PRODUCT; packages installed.</para>
</listitem>
<listitem>
<para>Edit as follows:</para>
<programlisting>
[upgrade]
name=rhel63
baseurl=url-of-your-rhel6.3-repo
enabled=1
gpgcheck=0
[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 baseurl
to http:// cloudstack.apt-get.eu/rhel/4.2/</para>
<para>If you are using your own package repository, change this line to read as
appropriate for your 4.2.0 repository.</para>
</listitem>
<listitem>
<para>Now that you have the repository configured, upgrade the host operating system
from RHEL 6.0 to 6.3:</para>
<programlisting># yum upgrade</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem id="stopping-usage-servers">
<para>Stop all Usage Servers if running. Run this on all Usage Server hosts.</para>
<programlisting language="Bash"><prompt>#</prompt> service cloud-usage stop</programlisting>
</listitem>
<listitem>
<para>Stop the Management Servers. Run this on all Management Server hosts.</para>
<programlisting language="Bash"><prompt>#</prompt> service cloud-management stop</programlisting>
</listitem>
<listitem>
<para>On the MySQL master, take a backup of the MySQL databases. We recommend performing
this step even in test upgrades. If there is an issue, this will assist with
debugging.</para>
<para>In the following commands, it is assumed that you have set the root password on the
database, which is a CloudStack recommended best practice. Substitute your own MySQL
root password.</para>
<programlisting><prompt>#</prompt> <command>mysqldump</command> -u root -p<replaceable>mysql_password</replaceable> cloud > <filename>cloud-backup.dmp</filename>
<prompt>#</prompt> <command>mysqldump</command> -u root -p<replaceable>mysql_password</replaceable> cloud_usage > <filename>cloud-usage-backup.dmp</filename></programlisting>
</listitem>
<listitem>
<para>Either build RPM/DEB packages as detailed in the Installation Guide, or use one of
the community provided yum/apt repositories to gain access to the &PRODUCT;
binaries.</para>
</listitem>
<listitem id="upgrade-deb-packages-302">
<para>If you are using Ubuntu, follow this procedure to upgrade your packages. If not,
skip to step <xref linkend="upgrade-rpm-packages-302"/>.</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 numeration="loweralpha" id="debsteps-302">
<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-302">
<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-302">
<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 cloud-agent stop
killall jsvc
service cloudstack-agent start
</programlisting>
</listitem>
<listitem>
<para>During the upgrade, <filename>log4j-cloud.xml</filename> was simply copied over,
so the logs will continue to be added to
<filename>/var/log/cloud/agent/agent.log</filename>. There's nothing
<emphasis>wrong</emphasis> with this, but if you prefer to be consistent, you can
change this by copying over the sample configuration file:</para>
<programlisting language="Bash">
cd /etc/cloudstack/agent
mv log4j-cloud.xml.dpkg-dist log4j-cloud.xml
service cloudstack-agent restart
</programlisting>
</listitem>
<listitem>
<para>Once the agent is running, you can uninstall the old cloud-* packages from your
system:</para>
<programlisting language="Bash">sudo dpkg --purge cloud-agent</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem id="upgrade-rpm-packages-302">
<para>If you are using CentOS or RHEL, follow this procedure to upgrade your packages. If
not, skip to step <xref linkend="correct-components-xml-302"/>.</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 numeration="loweralpha" id="rpmsteps-302">
<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. (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 baseurl
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.2.0 repository.</para>
</listitem>
<listitem id="rpm-master-302">
<para>Now that you have the repository configured, it's time to install the
<filename>cloudstack-management</filename> package by upgrading the older
<filename>cloud-client</filename> package.</para>
<programlisting language="Bash">$ sudo yum upgrade cloud-client</programlisting>
</listitem>
<listitem id="kvm-agent-rpm-302">
<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 cloud-agent</programlisting>
<para>During the installation of <filename>cloudstack-agent</filename>, the RPM 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>
</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 cloud-agent stop
killall jsvc
service cloudstack-agent start
</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem id="correct-components-xml-302">
<para>If you have made changes to your copy of
<filename>/etc/cloud/management/components.xml</filename> the changes will be
preserved in the upgrade. However, you need to do the following steps to place these
changes in a new version of the file which is compatible with version 4.2.0.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Make a backup copy of <filename>/etc/cloud/management/components.xml</filename>.
For example:</para>
<programlisting># mv /etc/cloud/management/components.xml /etc/cloud/management/components.xml-backup</programlisting>
</listitem>
<listitem>
<para>Copy <filename>/etc/cloud/management/components.xml.rpmnew</filename> to create
a new <filename>/etc/cloud/management/components.xml</filename>:</para>
<programlisting># cp -ap /etc/cloud/management/components.xml.rpmnew /etc/cloud/management/components.xml</programlisting>
</listitem>
<listitem>
<para>Merge your changes from the backup file into the new
<filename>components.xml</filename>.</para>
<programlisting># vi /etc/cloudstack/management/components.xml</programlisting>
</listitem>
</orderedlist>
<note>
<para>If you have more than one management server node, repeat the upgrade steps on each
node.</para>
</note>
</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 componentContext.xml, and make PlainTextUserAuthenticator as the default
authenticator (1st entry in the userAuthenticators adapter list is default)</para>
<programlisting language="XML">
&lt;!-- Security adapters --&gt;
&lt;bean id="userAuthenticators" class="com.cloud.utils.component.AdapterList"&gt;
&lt;property name="Adapters"&gt;
&lt;list&gt;
&lt;ref bean="PlainTextUserAuthenticator"/&gt;
&lt;ref bean="MD5UserAuthenticator"/&gt;
&lt;ref bean="LDAPUserAuthenticator"/&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/bean&gt;
</programlisting>
<para>PlainTextUserAuthenticator works the same way MD5UserAuthenticator worked prior to
4.3</para>
</listitem>
<listitem>
<para>Start the first Management Server. Do not start any other Management Server nodes
yet.</para>
<programlisting language="Bash"><prompt>#</prompt> service cloudstack-management start</programlisting>
<para>Wait until the databases are upgraded. Ensure that the database upgrade is complete.
After confirmation, start the other Management Servers one at a time by running the same
command on each node.</para>
<note>
<para>Failing to restart the Management Server indicates a problem in the upgrade.
Having the Management Server restarted without any issues indicates that the upgrade
is successfully completed.</para>
</note>
</listitem>
<listitem>
<para>Start all Usage Servers (if they were running on your previous version). Perform
this on each Usage Server host.</para>
<para><command># service cloudstack-usage start</command></para>
</listitem>
<listitem>
<para>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 a yum or apt repository containing the &PRODUCT; packages as outlined
in the Installation Guide.</para>
</listitem>
<listitem>
<para>Stop the running agent.</para>
<para><command># service cloud-agent stop</command></para>
</listitem>
<listitem>
<para>Update the agent software with one of the following command sets as appropriate
for your environment.</para>
<para><command># yum update cloud-*</command></para>
<para><command># apt-get update</command></para>
<para><command># apt-get upgrade cloud-*</command></para>
</listitem>
<listitem>
<para>Edit <filename>/etc/cloudstack/agent/agent.properties</filename> to change the
resource parameter from
"com.cloud.agent.resource.computing.LibvirtComputingResource" to
"com.cloud.hypervisor.kvm.resource.LibvirtComputingResource".</para>
</listitem>
<listitem>
<para>Upgrade all the existing bridge names to new bridge names by running this
script:</para>
<programlisting> # cloudstack-agent-upgrade</programlisting>
</listitem>
<listitem>
<para> Install a libvirt hook with the following commands:</para>
<programlisting> # mkdir /etc/libvirt/hooks
# cp /usr/share/cloudstack-agent/lib/libvirtqemuhook /etc/libvirt/hooks/qemu
# chmod +x /etc/libvirt/hooks/qemu</programlisting>
</listitem>
<listitem>
<para>Restart libvirtd.</para>
<programlisting># service libvirtd restart</programlisting>
</listitem>
<listitem>
<para>Start the agent.</para>
<programlisting># service cloudstack-agent start</programlisting>
</listitem>
<listitem>
<para>When the Management Server is up and running, log in to the &PRODUCT; UI and
restart the virtual router for proper functioning of all the features.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Log in to the CloudStack UI as administrator, and check the status of the hosts. All
hosts should come to Up state (except those that you know to be offline). You may need
to wait 20 or 30 minutes, depending on the number of hosts.</para>
<note>
<para>Troubleshooting: If login fails, clear your browser cache and reload the
page.</para>
</note>
<para>Do not proceed to the next step until the hosts show in Up state.</para>
</listitem>
<listitem>
<para>If you are upgrading from 3.0.x, perform the following:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Ensure that the admin port is set to 8096 by using the "integration.api.port"
global parameter.</para>
<para>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.</para>
</listitem>
<listitem>
<para>Restart the Management Server.</para>
<note>
<para>If you don't want the admin port to remain open, you can set it to null after
the upgrade is done and restart the management server.</para>
</note>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Run the <command>cloudstack-sysvmadm</command> script to stop, then start, all
Secondary Storage VMs, Console Proxy VMs, and virtual routers. Run the script once on
each management server. Substitute your own IP address of the MySQL instance, the MySQL
user to connect as, and the password to use for that user. In addition to those
parameters, provide the <command>-c</command> and <command>-r</command> arguments. For
example:</para>
<para><command># nohup cloudstack-sysvmadm -d 192.168.1.5 -u cloud -p password -c -r >
sysvm.log 2>&amp;1 &amp;</command></para>
<para><command># tail -f sysvm.log</command></para>
<para>This might take up to an hour or more to run, depending on the number of accounts in
the system.</para>
</listitem>
<listitem>
<para>If needed, upgrade all Citrix XenServer hypervisor hosts in your cloud to a version
supported by CloudStack 4.3. The supported versions are XenServer 5.6 SP2 and 6.0.2.
Instructions for upgrade can be found in the CloudStack 4.3 Installation Guide under
"Upgrading XenServer Versions."</para>
</listitem>
<listitem>
<para>Now apply the XenServer hotfix XS602E003 (and any other needed hotfixes) to
XenServer v6.0.2 hypervisor hosts.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Disconnect the XenServer cluster from CloudStack.</para>
<para>In the left navigation bar of the CloudStack UI, select Infrastructure. Under
Clusters, click View All. Select the XenServer cluster and click Actions -
Unmanage.</para>
<para>This may fail if there are hosts not in one of the states Up, Down,
Disconnected, or Alert. You may need to fix that before unmanaging this
cluster.</para>
<para>Wait until the status of the cluster has reached Unmanaged. Use the CloudStack
UI to check on the status. When the cluster is in the unmanaged state, there is no
connection to the hosts in the cluster.</para>
</listitem>
<listitem>
<para>To clean up the VLAN, log in to one XenServer host and run:</para>
<para><command>/opt/xensource/bin/cloud-clean-vlan.sh</command></para>
</listitem>
<listitem>
<para>Now prepare the upgrade by running the following on one XenServer host:</para>
<para><command>/opt/xensource/bin/cloud-prepare-upgrade.sh</command></para>
<para>If you see a message like "can't eject CD", log in to the VM and unmount the CD,
then run this script again.</para>
</listitem>
<listitem>
<para>Upload the hotfix to the XenServer hosts. Always start with the Xen pool master,
then the slaves. Using your favorite file copy utility (e.g. WinSCP), copy the
hotfixes to the host. Place them in a temporary folder such as /tmp. </para>
<para>On the Xen pool master, upload the hotfix with this command:</para>
<para><command>xe patch-upload file-name=XS602E003.xsupdate</command></para>
<para>Make a note of the output from this command, which is a UUID for the hotfix
file. You'll need it in another step later.</para>
<note>
<para>(Optional) If you are applying other hotfixes as well, you can repeat the
commands in this section with the appropriate hotfix number. For example,
XS602E004.xsupdate.</para>
</note>
</listitem>
<listitem>
<para>Manually live migrate all VMs on this host to another host. First, get a list of
the VMs on this host:</para>
<para><command># xe vm-list</command></para>
<para>Then use this command to migrate each VM. Replace the example host name and VM
name with your own:</para>
<para><command># xe vm-migrate live=true host=<replaceable>host-name</replaceable>
vm=<replaceable>VM-name</replaceable></command></para>
<note>
<title>Troubleshooting</title>
<para>If you see a message like "You attempted an operation on a VM which requires
PV drivers to be installed but the drivers were not detected," run:</para>
<para><command>/opt/xensource/bin/make_migratable.sh
b6cf79c8-02ee-050b-922f-49583d9f1a14</command>.</para>
</note>
</listitem>
<listitem>
<para>Apply the hotfix. First, get the UUID of this host:</para>
<programlisting># xe host-list</programlisting>
<para>Then use the following command to apply the hotfix. Replace the example host
UUID with the current host ID, and replace the hotfix UUID with the output from the
patch-upload command you ran on this machine earlier. You can also get the hotfix
UUID by running xe patch-list. </para>
<programlisting><command>xe</command> patch-apply host-uuid=<replaceable>host-uuid</replaceable> uuid=<replaceable>hotfix-uuid</replaceable></programlisting>
</listitem>
<listitem>
<para>Copy the following files from the CloudStack Management Server to the
host.</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>Copy from here...</para></entry>
<entry><para>...to here</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>/usr/lib64/cloud/common/scripts/vm/hypervisor/xenserver/xenserver60/NFSSR.py</para></entry>
<entry><para>/opt/xensource/sm/NFSSR.py</para></entry>
</row>
<row>
<entry><para>/usr/lib64/cloud/common/scripts/vm/hypervisor/xenserver/setupxenserver.sh</para></entry>
<entry><para>/opt/xensource/bin/setupxenserver.sh</para></entry>
</row>
<row>
<entry><para>/usr/lib64/cloud/common/scripts/vm/hypervisor/xenserver/make_migratable.sh</para></entry>
<entry><para>/opt/xensource/bin/make_migratable.sh</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
<listitem>
<para>(Only for hotfixes XS602E005 and XS602E007) You need to apply a new Cloud
Support Pack.</para>
<itemizedlist>
<listitem>
<para>Download the CSP software onto the XenServer host from one of the following
links:</para>
<para>For hotfix XS602E005: <ulink
url="http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E005/56710/xe-phase-2/xenserver-cloud-supp.tgz"
>http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E005/56710/xe-phase-2/xenserver-cloud-supp.tgz</ulink></para>
<para>For hotfix XS602E007: <ulink
url="http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E007/57824/xe-phase-2/xenserver-cloud-supp.tgz"
>http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E007/57824/xe-phase-2/xenserver-cloud-supp.tgz</ulink></para>
</listitem>
<listitem>
<para>Extract the file:</para>
<programlisting># tar xf xenserver-cloud-supp.tgz</programlisting>
</listitem>
<listitem>
<para>Run the following script:</para>
<programlisting># xe-install-supplemental-pack xenserver-cloud-supp.iso</programlisting>
</listitem>
<listitem>
<para>If the XenServer host is part of a zone that uses basic networking, disable
Open vSwitch (OVS):</para>
<programlisting># xe-switch-network-backend bridge</programlisting>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Reboot this XenServer host.</para>
</listitem>
<listitem>
<para>Run the following:</para>
<programlisting>/opt/xensource/bin/setupxenserver.sh</programlisting>
<note>
<para>If the message "mv: cannot stat `/etc/cron.daily/logrotate': No such file or
directory" appears, you can safely ignore it.</para>
</note>
</listitem>
<listitem>
<para>Run the following:</para>
<programlisting>for pbd in `xe pbd-list currently-attached=false| grep ^uuid | awk '{print $NF}'`; do xe pbd-plug uuid=$pbd ; </programlisting>
</listitem>
<listitem>
<para>On each slave host in the Xen pool, repeat these steps, starting from "manually
live migrate VMs."</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
<note>
<title>Troubleshooting Tip</title>
<para>If passwords which you know to be valid appear not to work after upgrade, or other UI
issues are seen, try clearing your browser cache and reloading the UI page.</para>
</note>
</section>
<section id="upgrade-from-2.2.x-to-4.3">
<title>Upgrade from 2.2.14 to 4.3</title>
<orderedlist>
<listitem>
<para>Ensure that you query your IPaddress usage records and process them; for example,
issue invoices for any usage that you have not yet billed users for.</para>
<para>Starting in 3.0.2, the usage record format for IP addresses is the same as the rest
of the usage types. Instead of a single record with the assignment and release dates,
separate records are generated per aggregation period with start and end dates. After
upgrading to 4.3, any existing IP address usage records in the old format will no longer
be available.</para>
</listitem>
<listitem>
<para>If you are using version 2.2.0 - 2.2.13, first upgrade to 2.2.14 by using the
instructions in the <ulink
url="http://download.cloud.com/releases/2.2.0/CloudStack2.2.14ReleaseNotes.pdf">2.2.14
Release Notes</ulink>.</para>
<warning>
<title>KVM Hosts</title>
<para>If KVM hypervisor is used in your cloud, be sure you completed the step to insert
a valid username and password into the host_details table on each KVM node as
described in the 2.2.14 Release Notes. This step is critical, as the database will be
encrypted after the upgrade to 4.3.</para>
</warning>
</listitem>
<listitem>
<para>While running the 2.2.14 system, log in to the UI as root administrator.</para>
</listitem>
<listitem>
<para>Using the UI, add a new System VM template for each hypervisor type that is used in
your cloud. In each zone, add a system VM template for each hypervisor used in that
zone</para>
<orderedlist>
<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 depending on
the hypervisor type (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>Watch the screen to be sure that the template downloads successfully and enters the
READY state. Do not proceed until this is successful</para>
</listitem>
<listitem>
<para><emphasis role="bold">WARNING</emphasis>: If you use more than one type of
hypervisor in your cloud, be sure you have repeated these steps to download the system
VM template for each hypervisor type. Otherwise, the upgrade will fail.</para>
</listitem>
<listitem>
<para>(KVM on RHEL 6.0/6.1 only) If your existing &PRODUCT; deployment includes one or
more clusters of KVM hosts running RHEL 6.0 or RHEL 6.1, perform the following:</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Ensure that you upgrade the operating system version on those hosts before
upgrading &PRODUCT;</para>
<para>To do that, change the yum repository for each system with &PRODUCT; packages,
that implies that all the Management Servers and any hosts that have the KVM agent.
</para>
</listitem>
<listitem>
<para>Open <filename>/etc/yum.repos.d/cloudstack.repo</filename> on any systems that
have &PRODUCT; packages installed.</para>
</listitem>
<listitem>
<para>Edit as follows:</para>
<programlisting>
[upgrade]
name=rhel63
baseurl=url-of-your-rhel6.3-repo
enabled=1
gpgcheck=0
[apache CloudStack]
name= Apache CloudStack
baseurl= http://cloudstack.apt-get.eu/rhel/4.2/
enabled=1
gpgcheck=0</programlisting>
<para>If you are using the community provided package repository, change the baseurl
to http:// cloudstack.apt-get.eu/rhel/4.2/</para>
<para>If you are using your own package repository, change this line to read as
appropriate for your 4.2.0 repository.</para>
</listitem>
<listitem>
<para>Now that you have the repository configured, upgrade the host operating system
from RHEL 6.0 to 6.3:</para>
<programlisting># yum upgrade</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Stop all Usage Servers if running. Run this on all Usage Server hosts.</para>
<programlisting># service cloud-usage stop</programlisting>
</listitem>
<listitem>
<para>Stop the Management Servers. Run this on all Management Server hosts.</para>
<programlisting language="Bash"><prompt>#</prompt> service cloud-management stop</programlisting>
</listitem>
<listitem>
<para>On the MySQL master, take a backup of the MySQL databases. We recommend performing
this step even in test upgrades. If there is an issue, this will assist with
debugging.</para>
<para>In the following commands, it is assumed that you have set the root password on the
database, which is a CloudStack recommended best practice. Substitute your own MySQL
root password.</para>
<programlisting><prompt>#</prompt> <command>mysqldump</command> -u root -p<replaceable>mysql_password</replaceable> cloud > <filename>cloud-backup.dmp</filename>
<prompt>#</prompt> <command>mysqldump</command> -u root -p<replaceable>mysql_password</replaceable> cloud_usage > <filename>cloud-usage-backup.dmp</filename>
</programlisting>
</listitem>
<listitem>
<para> Either build RPM/DEB packages as detailed in the Installation Guide, or use one of
the community provided yum/apt repositories to gain access to the &PRODUCT; binaries.
</para>
</listitem>
<listitem id="upgrade-deb-packages-22">
<para>If you are using Ubuntu, follow this procedure to upgrade your packages. If not,
skip to step <xref linkend="upgrade-rpm-packages-22"/>.</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 numeration="loweralpha" id="debsteps-22">
<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.2.0 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-22">
<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-22">
<para>On KVM hosts, 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 cloud-agent stop
killall jsvc
service cloudstack-agent start
</programlisting>
</listitem>
<listitem>
<para>During the upgrade, <filename>log4j-cloud.xml</filename> was simply copied over,
so the logs will continue to be added to
<filename>/var/log/cloud/agent/agent.log</filename>. There's nothing
<emphasis>wrong</emphasis> with this, but if you prefer to be consistent, you can
change this by copying over the sample configuration file:</para>
<programlisting language="Bash">
cd /etc/cloudstack/agent
mv log4j-cloud.xml.dpkg-dist log4j-cloud.xml
service cloudstack-agent restart
</programlisting>
</listitem>
<listitem>
<para>Once the agent is running, you can uninstall the old cloud-* packages from your
system:</para>
<programlisting language="Bash">sudo dpkg --purge cloud-agent</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem id="upgrade-rpm-packages-22">
<para>If you are using CentOS or RHEL, follow this procedure to upgrade your packages. If
not, skip to step <xref linkend="correct-components-xml-22"/>.</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 numeration="loweralpha" id="rpmsteps-22">
<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. (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 baseurl
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-22">
<para>Now that you have the repository configured, it's time to install the
<filename>cloudstack-management</filename> package by upgrading the older
<filename>cloud-client</filename> package.</para>
<programlisting language="Bash">$ sudo yum upgrade cloud-client</programlisting>
</listitem>
<listitem id="kvm-agent-rpm-22">
<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 cloud-agent</programlisting>
<para>During the installation of <filename>cloudstack-agent</filename>, the RPM 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>
</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 cloud-agent stop
killall jsvc
service cloudstack-agent start
</programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem id="correct-components-xml-22">
<para>If you have made changes to your existing copy of the file components.xml in your
previous-version CloudStack installation, the changes will be preserved in the upgrade.
However, you need to do the following steps to place these changes in a new version of
the file which is compatible with version 4.0.0-incubating.</para>
<note>
<para>How will you know whether you need to do this? If the upgrade output in the
previous step included a message like the following, then some custom content was
found in your old components.xml, and you need to merge the two files:</para>
</note>
<programlisting>warning: /etc/cloud/management/components.xml created as /etc/cloud/management/components.xml.rpmnew </programlisting>
<orderedlist numeration="loweralpha">
<listitem>
<para>Make a backup copy of your
<filename>/etc/cloud/management/components.xml</filename> file. For
example:</para>
<programlisting><prompt>#</prompt> <command>mv</command> <filename>/etc/cloud/management/components.xml</filename> <filename>/etc/cloud/management/components.xml-backup</filename></programlisting>
</listitem>
<listitem>
<para>Copy <filename>/etc/cloud/management/components.xml.rpmnew</filename> to create
a new <filename>/etc/cloud/management/components.xml</filename>:</para>
<programlisting><prompt>#</prompt> <command>cp</command> -ap <filename>/etc/cloud/management/components.xml.rpmnew</filename> <filename>/etc/cloud/management/components.xml</filename></programlisting>
</listitem>
<listitem>
<para>Merge your changes from the backup file into the new components.xml file.</para>
<programlisting><prompt>#</prompt> <command>vi</command> <filename>/etc/cloudstack/management/components.xml</filename>
</programlisting>
</listitem>
</orderedlist>
</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. If API client changes are not acceptable,
following changes are to be made for backward compatibility:</para>
<para>Modify componentContext.xml, and make PlainTextUserAuthenticator as the default
authenticator (1st entry in the userAuthenticators adapter list is default)</para>
<programlisting language="XML">
&lt;!-- Security adapters --&gt;
&lt;bean id="userAuthenticators" class="com.cloud.utils.component.AdapterList"&gt;
&lt;property name="Adapters"&gt;
&lt;list&gt;
&lt;ref bean="PlainTextUserAuthenticator"/&gt;
&lt;ref bean="MD5UserAuthenticator"/&gt;
&lt;ref bean="LDAPUserAuthenticator"/&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/bean&gt;
</programlisting>
<para>PlainTextUserAuthenticator works the same way MD5UserAuthenticator worked prior to
4.2.</para>
</listitem>
<listitem>
<para>If you have made changes to your existing copy of the
<filename>/etc/cloud/management/db.properties</filename> file in your previous-version
CloudStack installation, the changes will be preserved in the upgrade. However, you need
to do the following steps to place these changes in a new version of the file which is
compatible with this version.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Make a backup copy of your file
<filename>/etc/cloud/management/db.properties</filename>. For example:</para>
<programlisting><prompt>#</prompt> <command>mv</command> <filename>/etc/cloud/management/db.properties</filename> <filename>/etc/cloud/management/db.properties-backup</filename></programlisting>
</listitem>
<listitem>
<para>Copy <filename>/etc/cloud/management/db.properties.rpmnew</filename> to create a
new <filename>/etc/cloud/management/db.properties</filename>:</para>
<programlisting><prompt>#</prompt> <command>cp</command> -ap <filename>/etc/cloud/management/db.properties.rpmnew</filename> <filename>etc/cloud/management/db.properties</filename></programlisting>
</listitem>
<listitem>
<para>Merge your changes from the backup file into the new db.properties file.</para>
<programlisting><prompt>#</prompt> <command>vi</command> <filename>/etc/cloudstack/management/db.properties</filename></programlisting>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>On the management server node, run the following command. It is recommended that you
use the command-line flags to provide your own encryption keys. See Password and Key
Encryption in the Installation Guide.</para>
<programlisting><prompt>#</prompt> <command>cloudstack-setup-encryption</command> -e <replaceable>encryption_type</replaceable> -m <replaceable>management_server_key</replaceable> -k <replaceable>database_key</replaceable></programlisting>
<para>When used without arguments, as in the following example, the default encryption
type and keys will be used:</para>
<itemizedlist>
<listitem>
<para>(Optional) For encryption_type, use file or web to indicate the technique used
to pass in the database encryption password. Default: file.</para>
</listitem>
<listitem>
<para>(Optional) For management_server_key, substitute the default key that is used to
encrypt confidential parameters in the properties file. Default: password. It is
highly recommended that you replace this with a more secure value</para>
</listitem>
<listitem>
<para>(Optional) For database_key, substitute the default key that is used to encrypt
confidential parameters in the CloudStack database. Default: password. It is highly
recommended that you replace this with a more secure value.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Repeat steps 10 - 14 on every management server node. If you provided your own
encryption key in step 14, use the same key on all other management servers.</para>
</listitem>
<listitem>
<para>Start the first Management Server. Do not start any other Management Server nodes
yet.</para>
<programlisting language="Bash"><prompt>#</prompt> service cloudstack-management start</programlisting>
<para>Wait until the databases are upgraded. Ensure that the database upgrade is complete.
You should see a message like "Complete! Done." After confirmation, start the other
Management Servers one at a time by running the same command on each node.</para>
</listitem>
<listitem>
<para>Start all Usage Servers (if they were running on your previous version). Perform
this on each Usage Server host.</para>
<programlisting language="Bash"><prompt>#</prompt> service cloudstack-usage start</programlisting>
</listitem>
<listitem>
<para>(KVM only) Perform the following additional steps on each KVM host. </para>
<para>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 your CloudStack package repositories as outlined in the Installation
Guide </para>
</listitem>
<listitem>
<para>Stop the running agent.</para>
<programlisting># service cloud-agent stop</programlisting>
</listitem>
<listitem>
<para>Update the agent software with one of the following command sets as
appropriate.</para>
<programlisting><prompt>#</prompt> <command>yum</command> update cloud-*</programlisting>
<programlisting>
<prompt>#</prompt> <command>apt-get</command> update
<prompt>#</prompt> <command>apt-get</command> upgrade cloud-*
</programlisting>
</listitem>
<listitem>
<para> Copy the contents of the <filename>agent.properties</filename> file to the new
<filename>agent.properties</filename> file by using the following command</para>
<programlisting><command>sed</command> -i 's/com.cloud.agent.resource.computing.LibvirtComputingResource/com.cloud.hypervisor.kvm.resource.LibvirtComputingResource/g' <filename>/etc/cloudstack/agent/agent.properties</filename></programlisting>
</listitem>
<listitem>
<para>Upgrade all the existing bridge names to new bridge names by running this
script:</para>
<programlisting> # cloudstack-agent-upgrade</programlisting>
</listitem>
<listitem>
<para> Install a libvirt hook with the following commands:</para>
<programlisting> # mkdir /etc/libvirt/hooks
# cp /usr/share/cloudstack-agent/lib/libvirtqemuhook /etc/libvirt/hooks/qemu
# chmod +x /etc/libvirt/hooks/qemu</programlisting>
</listitem>
<listitem>
<para>Restart libvirtd.</para>
<programlisting># service libvirtd restart</programlisting>
</listitem>
<listitem>
<para>Start the agent.</para>
<programlisting># service cloudstack-agent start</programlisting>
</listitem>
<listitem>
<para>When the Management Server is up and running, log in to the CloudStack UI and
restart the virtual router for proper functioning of all the features.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Log in to the CloudStack UI as admin, and check the status of the hosts. All hosts
should come to Up state (except those that you know to be offline). You may need to wait
20 or 30 minutes, depending on the number of hosts.</para>
<para>Do not proceed to the next step until the hosts show in the Up state. If the hosts
do not come to the Up state, contact support.</para>
</listitem>
<listitem>
<para>Run the following script to stop, then start, all Secondary Storage VMs, Console
Proxy VMs, and virtual routers.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Run the command once on one management server. Substitute your own IP address of
the MySQL instance, the MySQL user to connect as, and the password to use for that
user. In addition to those parameters, provide the "-c" and "-r" arguments. For
example:</para>
<programlisting><prompt>#</prompt> <command>nohup cloudstack-sysvmadm</command> -d <replaceable>192.168.1.5</replaceable> -u cloud -p <replaceable>password</replaceable> -c -r > sysvm.log 2>&amp;1 &amp;
<prompt>#</prompt> <command>tail</command> -f <filename>sysvm.log</filename></programlisting>
<para>This might take up to an hour or more to run, depending on the number of
accounts in the system.</para>
</listitem>
<listitem>
<para>After the script terminates, check the log to verify correct execution:</para>
<programlisting><prompt>#</prompt> <command>tail</command> -f <filename>sysvm.log</filename></programlisting>
<para>The content should be like the following:</para>
<programlisting>
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>
</orderedlist>
</listitem>
<listitem>
<para>If you would like additional confirmation that the new system VM templates were
correctly applied when these system VMs were rebooted, SSH into the System VM and check
the version.</para>
<para>Use one of the following techniques, depending on the hypervisor.</para>
<formalpara>
<title>XenServer or KVM:</title>
<para>SSH in by using the link local IP address of the system VM. For example, in the
command below, substitute your own path to the private key used to log in to the
system VM and your own link local IP.</para>
</formalpara>
<para>Run the following commands on the XenServer or KVM host on which the system VM is
present:</para>
<programlisting><prompt>#</prompt> <command>ssh</command> -i <replaceable>private-key-path</replaceable> <replaceable>link-local-ip</replaceable> -p 3922
# cat /etc/cloudstack-release</programlisting>
<para>The output should be like the following:</para>
<programlisting>Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 2012</programlisting>
<formalpara>
<title>ESXi</title>
<para>SSH in using the private IP address of the system VM. For example, in the command
below, substitute your own path to the private key used to log in to the system VM and
your own private IP.</para>
</formalpara>
<para>Run the following commands on the Management Server:</para>
<programlisting><prompt>#</prompt> <command>ssh</command> -i <replaceable>private-key-path</replaceable> <replaceable>private-ip</replaceable> -p 3922
<prompt>#</prompt> <command>cat</command> <filename>/etc/cloudstack-release</filename>
</programlisting>
<para>The output should be like the following:</para>
<programlisting>Cloudstack Release 4.0.0-incubating Mon Oct 9 15:10:04 PST 2012</programlisting>
</listitem>
<listitem>
<para>If needed, upgrade all Citrix XenServer hypervisor hosts in your cloud to a version
supported by CloudStack 4.0.0-incubating. The supported versions are XenServer 5.6 SP2
and 6.0.2. Instructions for upgrade can be found in the CloudStack 4.0.0-incubating
Installation Guide.</para>
</listitem>
<listitem>
<para>Apply the XenServer hotfix XS602E003 (and any other needed hotfixes) to XenServer
v6.0.2 hypervisor hosts.</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>Disconnect the XenServer cluster from CloudStack.</para>
<para>In the left navigation bar of the CloudStack UI, select Infrastructure. Under
Clusters, click View All. Select the XenServer cluster and click Actions -
Unmanage.</para>
<para>This may fail if there are hosts not in one of the states Up, Down,
Disconnected, or Alert. You may need to fix that before unmanaging this
cluster.</para>
<para>Wait until the status of the cluster has reached Unmanaged. Use the CloudStack
UI to check on the status. When the cluster is in the unmanaged state, there is no
connection to the hosts in the cluster.</para>
</listitem>
<listitem>
<para>To clean up the VLAN, log in to one XenServer host and run:</para>
<programlisting>/opt/xensource/bin/cloud-clean-vlan.sh</programlisting>
</listitem>
<listitem>
<para>Prepare the upgrade by running the following on one XenServer host:</para>
<programlisting>/opt/xensource/bin/cloud-prepare-upgrade.sh</programlisting>
<para>If you see a message like "can't eject CD", log in to the VM and umount the CD,
then run this script again.</para>
</listitem>
<listitem>
<para>Upload the hotfix to the XenServer hosts. Always start with the Xen pool master,
then the slaves. Using your favorite file copy utility (e.g. WinSCP), copy the
hotfixes to the host. Place them in a temporary folder such as /root or /tmp. </para>
<para>On the Xen pool master, upload the hotfix with this command:</para>
<programlisting>xe patch-upload file-name=XS602E003.xsupdate</programlisting>
<para>Make a note of the output from this command, which is a UUID for the hotfix
file. You'll need it in another step later.</para>
<note>
<para>(Optional) If you are applying other hotfixes as well, you can repeat the
commands in this section with the appropriate hotfix number. For example,
XS602E004.xsupdate.</para>
</note>
</listitem>
<listitem>
<para>Manually live migrate all VMs on this host to another host. First, get a list of
the VMs on this host:</para>
<programlisting># xe vm-list</programlisting>
<para>Then use this command to migrate each VM. Replace the example host name and VM
name with your own:</para>
<programlisting><prompt>#</prompt> <command>xe</command> vm-migrate live=true host=<replaceable>host-name</replaceable> vm=<replaceable>VM-name</replaceable></programlisting>
<note>
<title>Troubleshooting</title>
<para>If you see a message like "You attempted an operation on a VM which requires
PV drivers to be installed but the drivers were not detected," run:</para>
<para><command>/opt/xensource/bin/make_migratable.sh
b6cf79c8-02ee-050b-922f-49583d9f1a14</command>.</para>
</note>
</listitem>
<listitem>
<para>Apply the hotfix. First, get the UUID of this host:</para>
<para><command># xe host-list</command></para>
<para>Then use the following command to apply the hotfix. Replace the example host
UUID with the current host ID, and replace the hotfix UUID with the output from the
patch-upload command you ran on this machine earlier. You can also get the hotfix
UUID by running xe patch-list. </para>
<para><command>xe patch-apply host-uuid=<replaceable>host-uuid</replaceable>
uuid=<replaceable>hotfix-uuid</replaceable></command></para>
</listitem>
<listitem>
<para>Copy the following files from the CloudStack Management Server to the
host.</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>Copy from here...</para></entry>
<entry><para>...to here</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para><filename>/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/xenserver60/NFSSR.py</filename></para></entry>
<entry><para><filename>/opt/xensource/sm/NFSSR.py</filename></para></entry>
</row>
<row>
<entry><para><filename>/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/setupxenserver.sh</filename></para></entry>
<entry><para><filename>/opt/xensource/bin/setupxenserver.sh</filename></para></entry>
</row>
<row>
<entry><para><filename>/usr/lib64/cloudstack-common/scripts/vm/hypervisor/xenserver/make_migratable.sh</filename></para></entry>
<entry><para><filename>/opt/xensource/bin/make_migratable.sh</filename></para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
<listitem>
<para>(Only for hotfixes XS602E005 and XS602E007) You need to apply a new Cloud
Support Pack.</para>
<itemizedlist>
<listitem>
<para>Download the CSP software onto the XenServer host from one of the following
links:</para>
<para>For hotfix XS602E005: <ulink
url="http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E005/56710/xe-phase-2/xenserver-cloud-supp.tgz"
>http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E005/56710/xe-phase-2/xenserver-cloud-supp.tgz</ulink></para>
<para>For hotfix XS602E007: <ulink
url="http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E007/57824/xe-phase-2/xenserver-cloud-supp.tgz"
>http://coltrane.eng.hq.xensource.com/release/XenServer-6.x/XS-6.0.2/hotfixes/XS602E007/57824/xe-phase-2/xenserver-cloud-supp.tgz</ulink></para>
</listitem>
<listitem>
<para>Extract the file:</para>
<para><command># tar xf xenserver-cloud-supp.tgz</command></para>
</listitem>
<listitem>
<para>Run the following script:</para>
<para><command># xe-install-supplemental-pack
xenserver-cloud-supp.iso</command></para>
</listitem>
<listitem>
<para>If the XenServer host is part of a zone that uses basic networking, disable
Open vSwitch (OVS):</para>
<para><command># xe-switch-network-backend bridge</command></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Reboot this XenServer host.</para>
</listitem>
<listitem>
<para>Run the following:</para>
<para><command>/opt/xensource/bin/setupxenserver.sh</command></para>
<note>
<para>If the message "mv: cannot stat `/etc/cron.daily/logrotate': No such file or
directory" appears, you can safely ignore it.</para>
</note>
</listitem>
<listitem>
<para>Run the following:</para>
<para><command>for pbd in `xe pbd-list currently-attached=false| grep ^uuid | awk
'{print $NF}'`; do xe pbd-plug uuid=$pbd ; </command>
</para>
</listitem>
<listitem>
<para>On each slave host in the Xen pool, repeat these steps, starting from "manually
live migrate VMs."</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</section>
</chapter>
<chapter id="api-changes-4.3">
<title>API Changes Introduced in 4.3</title>
<section id="hyperv-api">
<title>Hyper-V</title>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth="1.0*" colname="1" colnum="1"/>
<colspec colwidth="9.87*" colname="2" colnum="2"/>
<thead>
<row>
<entry><para>API</para></entry>
<entry><para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>addPrimaryStorage</para></entry>
<entry><para>To this existing API, the following field has been added:
smb</para></entry>
</row>
<row>
<entry><para>addImageStore</para></entry>
<entry><para>To this existing API, the following field has been added:
smb</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="socket-api">
<title>Reporting CPU Sockets</title>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth="1.0*" colname="1" colnum="1"/>
<colspec colwidth="9.87*" colname="2" colnum="2"/>
<thead>
<row>
<entry><para>API</para></entry>
<entry><para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>listhost</para></entry>
<entry><para>To this existing API, the following request parameter has been added:
hypervisor.</para><para>The new response parameter added is:
cpusockets</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="alert-api">
<title>Reporting CPU Sockets</title>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth="1.0*" colname="1" colnum="1"/>
<colspec colwidth="9.87*" colname="2" colnum="2"/>
<thead>
<row>
<entry><para>API</para></entry>
<entry><para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>generateAlert</para></entry>
<entry><para>A new API has been added to generate and publish alerts for usage
services. The usage services can be installed on a different host or the same host
where the Management Server is running.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="dynamic-compute">
<title>Dynamic Compute Offering</title>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth="1.0*" colname="1" colnum="1"/>
<colspec colwidth="9.87*" colname="2" colnum="2"/>
<thead>
<row>
<entry><para>API</para></entry>
<entry><para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>DeployVM</para></entry>
<entry><para>To this existing API, the following request parameter has been added:
details.</para></entry>
</row>
<row>
<entry><para>ScaleVM</para></entry>
<entry><para>To this existing API, the following request parameter has been added:
details.</para></entry>
</row>
<row>
<entry><para>ScaleSystemVM</para></entry>
<entry><para>To this existing API, the following request parameter has been added:
details.</para></entry>
</row>
<row>
<entry><para>UpgradeVM</para></entry>
<entry><para>To this existing API, the following request parameter has been added:
details.</para></entry>
</row>
<row>
<entry><para>UpgradeSysytemVM</para></entry>
<entry><para>To this existing API, the following request parameter has been added:
details.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section id="vr-api">
<title>Enhanced Upgrade for Virtual Routers</title>
<informaltable>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth="1.0*" colname="1" colnum="1"/>
<colspec colwidth="9.87*" colname="2" colnum="2"/>
<thead>
<row>
<entry><para>API</para></entry>
<entry><para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>upgradeRouterTemplate</para></entry>
<entry><para>This is a new API which has been added in this release.</para>
<para>The following are the request parameters:</para>
<itemizedlist>
<listitem>
<para>id: Upgrade the specified VR</para>
</listitem>
<listitem>
<para>zone_id : Upgrade the VRs in the specified zone.</para>
</listitem>
<listitem>
<para>pod_id : Upgrade the VRs in the specified pod.</para>
</listitem>
<listitem>
<para>cluster_id : Upgrade the VRs in the specified cluster.</para>
</listitem>
<listitem>
<para>domain_id : Upgrade the VRs belonging to the specified domain.</para>
</listitem>
<listitem>
<para>account_id : Upgrade the VRs belonging to the specified account.</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry><para>listRouters</para></entry>
<entry><para>For this existing API, the following request parameters has been
added:</para>
<itemizedlist>
<listitem>
<para>version: Lists routers by specified version.</para>
</listitem>
<listitem>
<para>zone_id : lists routers in specified zone.</para>
</listitem>
<listitem>
<para>pod_id : Lists routers in the specified pod.</para>
</listitem>
<listitem>
<para>cluster_id : Lists routers in the specified cluster.</para>
</listitem>
<listitem>
<para>domain_id : Lists routers owned by specified domain.</para>
</listitem>
<listitem>
<para>account: Lists routers owned by specified account.</para>
</listitem>
</itemizedlist>
<para>The following response parameters has been added:</para>
<itemizedlist>
<listitem>
<para>version : (String) The router version. For example, 4.3.0.</para>
</listitem>
<listitem>
<para>requiresupgrade: (Boolean) The flag to indicate if the router template
requires an upgrade.</para>
</listitem>
</itemizedlist></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</chapter>
</book>