Documentation

Skip to end of metadata
Go to start of metadata


Abiquo Wiki
Upgrading 3.1.x to 3.2

v3.2 2015-03-06

1. Description

The Abiquo 3.2.x packages upgrade the Abiquo platform servers of the Abiquo Monolithic and Abiquo Distributed installs.

Follow this documentation to upgrade every Abiquo Server (Remote Services, V2V, Abiquo Server).

Abiquo 3.2.x requires Java version 8 and therefore, all other Abiquo components (Abiquo AIM and Abiquo LVM) will need to be upgraded as well.
If you are using Oracle Java, you will need to update Oracle JCE (Java Cryptography Extension for encrypton) libraries to version 8.

 

1.1. Upgrade elements

Release Versionv3.2v3.2.1v3.2.2v3.2.3v3.2.4   
Abiquo
  • Properties
  • Configuration
  • Database
  • Redis
  • JCE encryption
  • Client config 
 
  • Signing key
  • Google Maps UI properties
  • Tutorials install and configuration
 
  • Password recovery UI properties
   
Other
  • KVM
  • LVM 
 KVM     

 

2. Prerequisites

This update is for Abiquo 3.1.x. To perform a fresh install, you should install version 3.2 directly from the Abiquo 3.2 ISO.

3. Preparation

Note

BEFORE upgrading to Abiquo 3.2.x ensure that you have a complete Abiquo backup

Remember to back up all customized elements, such as branding, configurations, language files, etc. After upgrading your system, reapply branding, reapply UI customizations, and check and reapply any other customizations if necessary. See Backup and Restore of Customization for Upgrading Abiquo .

3.1. Changes to UI client labels

Custom UI label files

You must copy all custom language files to the new file format lang_xx_XX_custom.json or the customized or translated labels will not be found

The lang_en_US.json file will be OVERWRITTEN during the upgrade

Abiquo 3.2 has a new language file for customization to UI client labels and API error messages. See Customizing and translating UI error messages

  • Before the upgrade to 3.2.x, customers should copy ANY existing custom UI label files and translations (e.g. lang_en_US.json and so on) and copy them to the new file format i.e. lang_xx_XX_custom.json.
    • If you do not change the names of these files, the custom or translated versions will not be found
  • During the upgrade, Abiquo will replace lang_en_US.json with the new version for Abiquo 3.2.x

4. Perform the server upgrade

4.1. Remove cloud user access

You can prevent cloud users from performing operations on VMs by accessing the platform and disabling all the physical machines in Abiquo (in Infrastructure view in the UI) or using the API (setting state to DISABLED). 

4.2. Ensure all queues are empty and no tasks are in progress

On Remote Services check the status of RabbitMQ to ensure that there are no outstanding tasks 

service rabbitmq-server status

This will provide the PID so you can see if it is running or not.

Secondly, check the consumers’ list:

 rabbitmqctl list_consumers

The result should be something like this but with more values:

abiquo.vsm.eventsynk ... ==true
abiquo.tracer.traces ... ==true
abiquo.datacenter.requests.Abiquo.virtualfactory ... ==true
abiquo.ha.tasks ... ==true
abiquo.am.downloads ... ==true
abiquo.datacenter.requests.Abiquo.bpm ... ==true
abiquo.datacenter.notifications ... ==true

All must be true.  

Finally check the queues: 

# rabbitmqctl list_queues

The output will be similar to this:

Listing queues ...
abiquo.vsm.eventsynk 0
abiquo.tracer.traces 0
abiquo.datacenter.requests.Abiquo.virtualfactory 0
abiquo.ha.tasks 0
abiquo.am.downloads 0
abiquo.datacenter.requests.Abiquo.bpm 0
abiquo.datacenter.notifications 0
...done.

You can check for any active V2V conversions by checking for the V2V or Mechadora processes

ps aux | grep v2v
ps aux | grep mechadora

See Service Management for details

4.3. Stop abiquo-tomcat service

service abiquo-tomcat stop

4.4. Upgrade with yum

4.4.1. Import new signing key

If you have not yet imported the new signing key (in v3.1.4 or v3.2.2), import it before the yum update

rpm --import http://mirror.abiquo.com/RPM-GPG-RSA-KEY-Abiquo

4.4.2. Change yum repos to Abiquo 3.2

Edit the /etc/yum.repos.d

/etc/yum.repos.d/Abiquo-Base.repo
# Ensure abiquo-base and abiquo-update repositories points to 3.2 version path


[abiquo-updates]
name=abiquo-updates-3.2
baseurl=http://mirror.abiquo.com/abiquo/3.2/updates/x86_64/
enabled=1
gpgcheck=1
priority=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Abiquo
 
[abiquo-base]
name=abiquo-base-3.2
baseurl=http://mirror.abiquo.com/abiquo/3.2/os/x86_64/
enabled=1
gpgcheck=1
priority=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Abiquo

 

4.4.3. Clean yum configuration

yum clean all

4.4.4. Run the yum upgrade command 

yum update

After yum update ensure your system is now using Java 8

# java -version
java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)

4.4.5. Java cacerts truststore

If your environment is running under SSL and you have needed to add certificates to the Java truststore before, you will need to:

  • migrate the old Java 7 truststore file (cacerts) to the new Java 8 version folder
     OR
  • add the certificates to the new truststore.

This procedure must be done on all Abiquo Servers on which you added a certificate to the Java truststore before.

To migrate the old truststore to new Java 8 version folder:

# Find Java 7 cacerts file
# export java7_truststore=$(find / -iname cacerts | grep 7 | grep jdk)
 
# Find Java 8 cacerts file
# export java8_truststore=$(find / -iname cacerts | grep 8 | grep jdk)
 
# Backup Java 8 cacerts file
# cp $java8_truststore ~/cacerts.java8.clean
 
# Replace Java 8 cacerts file with Java 7 cacerts file
# cp $java7_truststore $java8_truststore

4.5. Upgrade Abiquo database schema

 Ensure your hostname is in your DNS or in your /etc/hosts file.

Edit the script /usr/bin/abiquo-liquibase-update to add your DBUSER and DBPASSWORD

Run the script to update a local or remote database.

/usr/bin/abiquo-liquibase-update

 

4.6. Modify your configuration as required

First, see Configuration Changes in Abiquo 3.2 which describes all the changes in Abiquo 3.2.0. Further changes are described in the following section.

4.6.1. Changes in client configuration properties

You must add the following properties if they are not already present in your client-config.json file.

  • The Google Maps properties were introduced in Abiquo 3.2.2
  • The password recovery property was introduced in Abiquo 3.2.4

New Google Maps and password recovery client properties

You must add the following client properties when upgrading to Abiquo 3.2.x or the UI will not function properly. Remember to check your JSON file format: you must add a comma after each property, except for the last one. If you make an error in the file format, the UI will not load.

In Abiquo 3.2.x there are two new client configuration properties related to Google maps and one new property related to password recovery. These properties are mandatory in the client-config.json file.

Edit /var/www/html/ui/config/client-config.json. Go to the section where the other client.google properties can be found.

    ...
	"client.google.maps.enabled": true,
    "client.google.maps.key": "",
	"client.password.recovery": false,
	...

A sample configuration file with these properties included is available on the Abiquo Server at the following location

 /var/www/html/ui/config/client-config.json.rpmnew

 

4.6.2. Add Abiquo tutorials configuration

In Abiquo 3.2.2 there are two new client configuration properties related to Google maps. These properties are mandatory in the client-config.json file.

You must add the following Google maps properties when upgrading to Abiquo 3.2.2 or the UI will not function properly. Remember to check your JSON file format: you must add a comma after each property, except for the last one. If you make an error in the file format, the UI will not load.

Edit /var/www/html/ui/config/client-config.json. Go to the section where the other client.google properties can be found.

To enable Google Maps, set the enabled property to true. Include your Google Maps API key if required: see How to Obtain and Install a Google Maps API Key.

    ...
	"client.google.maps.enabled": true,
    "client.google.maps.key": "",
	...

A sample configuration file with these properties included is available on the Abiquo Server at the following location

 /var/www/html/ui/config/client-config.json.rpmnew

The Abiquo tutorials have now been moved to a separate package. When you upgrade the UI, the upgrade will install a symbolic link to the new tutorials directory.

Then you should install the tutorials with the following yum command.

yum install abiquo-tutorials

If you have customized the Abiquo tutorials, update the symbolic link to point to your own tutorials directory. For example

ln -s /opt/abiquo/mytutorials /var/www/html/ui/config/tutorials

Edit the Apache configuration, /etc/httpd/conf.d/abiquo.conf

Within the directive /var/www/html/ui, in the Options line, enable the option to follow symlinks by adding the FollowSymLinks option. For example, the first two lines of your directive could be as follows.

<Directory "/var/www/html/ui">
? ? ? ? Options MultiViews FollowSymLinks

4.7. Update JCE encryption libraries

Abiquo 3.1 installations running Oracle Java use the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.
As Abiquo 3.2 requires Java 8, update Java Cryptography Extension (JCE) libraries to the version for Java 8.

Oracle Java Cryptography Extension (JCE) 8 can be downloaded here: http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html

Once the file jce_policy-8.zip has been downloaded, extract the content and place it in $JAVA_HOME/jre/lib/security (you may need to install unzip from the Abiquo repo - yum install unzip).
A quicker way to do this is to combine the commands:

# If you are happy to accept the Oracle JCE license you can use these commands:
 
wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" http://download.oracle.com/otn-pub/java/jce/8/jce_policy-8.zip -O /tmp/JCE.zip && unzip /tmp/JCE.zip -d /tmp
 
mv /tmp/UnlimitedJCEPolicyJDK8/*.jar /usr/java/default/jre/lib/security/

This is a must in order for an upgraded installation to work. If the JCE jars are not available, Abiquo will not be able to communicate correctly with hypervisors, storage devices, and cloud providers. In this case you may see errors in the UI and errors in /opt/abiquo./tomcat/logs/catalina.out such as Unable to initialize due to invalid secret key

Ensure that JCE libraries have been updated by checking the md5sum

# md5sum /usr/java/default/jre/lib/security/*.jar
dabfcb23d7bf9bf5a201c3f6ea9bfb2c /usr/java/default/jre/lib/security/local_policy.jar
ef6e8eae7d1876d7f05d765d2c2e0529 /usr/java/default/jre/lib/security/US_export_policy.jar

4.8. Upgrade Redis schema

Check md5sum for redis-delta-3.0_to_3.2.py script file:

# md5sum /usr/share/doc/abiquo-remote-services/redis-deltas/redis-delta-3.0_to_3.2.py
333681c6a6bd305e0b4988344c433027 /usr/share/doc/abiquo-remote-services/redis-deltas/redis-delta-3.0_to_3.2.py

Execute the Redis delta script on each Abiquo Server running Redis (Abiquo Server and Abiquo RS nodes) to update the schema to the 3.2 version

# python /usr/share/doc/abiquo-remote-services/redis-deltas/redis-delta-3.0_to_3.2.py 

4.9. Update Abiquo UI client-config.json configuration

Abiquo 3.2 includes improvements and features that require new configuration properties in UI client-config.json.
By default, Abiquo does not overwrite the existing client-config.json file. Instead, a file named client-config.json.rpmnew is created in default configuration folder: /var/www/html/ui/config

Abiquo recommends that you should rename the existing configuration file and apply customizations to the new file. 

# mv /var/www/html/ui/config/client-config.json /var/www/html/ui/config/client-config.json.old.3.1

 
# cp /var/www/html/ui/config/client-config.json.rpmnew /var/www/html/ui/config/client-config.json
 
### And apply client-config.json.old.3.1 customizations to client-config.json

 

4.10. Start the abiquo-tomcat service

service abiquo-tomcat start

5. Abiquo LVM server upgrade

Abiquo LVM server upgrade is pretty similar to Abiquo Server upgrade.

5.1. Stop abiquo-lvmiscsi service

service abiquo-lvmiscsi stop

5.2. Upgrade abiquo-lvmiscsi

Follow steps:

  • 4.4.1 Change yum repos to Abiquo 3.2
  • 4.4.2 Clean yum configuration
  • 4.4.3 Run the yum upgrade command

5.3. Start abiquo-lvmiscsi service

service abiquo-lvmiscsi start

6. Abiquo KVM server node upgrade

Abiquo KVM server node upgrade is pretty similar to Abiquo Server upgrade.

6.1. Stop abiquo-aim service

service abiquo-aim stop

6.2. Upgrade abiquo-aim

Follow steps:

  • 4.4.1 Change yum repos to Abiquo 3.2
  • 4.4.2 Clean yum configuration
  • 4.4.3 Run the yum upgrade command

6.3. Start abiquo-aim service

service abiquo-aim start

7. Packages upgraded

The following packages are upgraded in Abiquo 3.2.x

See Upgrade to Abiquo 3.2.x patch versions

8. Post upgrade

8.1. Users clear browser cache

Important: Do NOT forget this step

Before logging in to Abiquo after an upgrade, all users must clear the browser cache on their machines. Check that the Abiquo GUI reports the correct version in the bottom left of the browser. 

8.2. Test the Upgrade

Perform basic testing to validate the installation, for example:

  1. Deploy VM
  2. Create instance
  3. Create persistent VM
  4. Deploy VM with external storage

9. Release Notes for Abiquo 3.2

See Also Release Notes