Skip to end of metadata
Go to start of metadata

Abiquo Wiki
Upgrading 3.0.1 to 3.1

v3.1 2014-08-14

1. Description

The Abiquo 3.1 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).

You do not need to upgrade KVM or LVM servers with this release.

2. Prerequisites

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

3. Preparation

Before making any changes to your system, ensure that you have a complete and validated system backup. Remember to back up all customized elements, such as branding. After upgrading your system, reapply branding, and check and reapply any other customizations as necessary. See Backup and Restore of Customization for Upgrading Abiquo

4. Perform the server upgrade

4.1. Remove cloud user access

You can prevent cloud users from accessing the platform by disabling all the physical machines in Abiquo (in Infrastructure view in the GUI) or using the API (setting state to HALTED).

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 ... ==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 0
abiquo.datacenter.requests.Abiquo.bpm 0
abiquo.datacenter.notifications 0

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. Change yum repos to Abiquo 3.1

Edit the /etc/yum.repos.d

name=CentOS-$releasever - Base
name=CentOS-$releasever - Updates


4.4.2. Clean yum configuration

yum clean all

4.4.3. Run the yum upgrade command 

yum update

4.5. Upgrade the database

 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.



4.6. Modify your configuration as required

See Configuration Changes in Abiquo 3.1

4.7. Credentials encryption

Starting in Abiquo 3.1.0 cloud providers, hypervisors and storage devices credentials are encrypted. In order to get Abiquo working, Java installations need Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy. This must be installed on every Abiquo server including Remote Services instances.

Oracle Java Cryptography Extension (JCE) can be downloaded here:

Once the file 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" -O /tmp/ && unzip /tmp/ -d /tmp
mv /tmp/UnlimitedJCEPolicy/*.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 or storage devices, as well as cloud providers. In this case you may see GEN-13 errors in the UI when adding public cloud credentials, and errors in /opt/abiquo./tomcat/logs/catalina.out such as Unable to initialize due to invalid secret key

4.7.1. Optionally set a custom encryption seed

Adding the JCE jar files to an Abiquo installation will suffice for it to work. Nonetheless, you might want to specify a custom encryption seed and avoid using the default one. You will need to follow the instructions below in order to set a custom encryption seed.

The encryption seed must be stored in the file /etc/abiquo/.store

Create the seed file mentioned before and type in a string that will be used as seed to encrypt all credentials stored in Abiquo databases (both MySQL and Redis). This seed MUST be the same in all Abiquo nodes (API and Remote Services). If this seed is lost and you don't have a backup you will need to regenerate ALL passwords stored in Abiquo as it won't be possible to use them again.

mkdir /etc/abiquo
vi /etc/abiquo/.store

Ensure that in each Abiquo node you've added the encryption property to file: = true

Abiquo will encrypt credentials even if no seed is supplied. If no seed file exists and the property is not set, a default seed will be used. If you set the property in your properties file, the seed file /etc/abiquo/.store MUST exist. If you create the seed file /etc/abiquo/.store but fail to set the property, the default seed will be used.

4.8. Encrypt current credentials

Last step is cypher existing passwords in Abiquo databases. You will need Abiquo encryptor tool, which must be executed once for the MySQL database, and once for every Redis. Note that each Remote Services instance runs Redis so you will need to execute these instructions on any separate Remote Services in your environment.

Uncompress the downloaded tarball:

# tar xzf encryptor-tool.tar.gz

As a result, you will get both a jar to run the tool and a README file with instructions on how to run the tool.

4.8.1. Using the encryption tool

To run the tool you need to launch the jar file as described below.

# java [Options] -Xms128m -jar path/to/encryptor-1.0.0.jar

Available options include:

  • db.update: whether the database must be migrated in this execution. Default false.
  • redis.update: whether redis must be migrated in this execution. Default false.
  • db.user: login credentials to database. Default root.
  • db.pass: password to database. Default emtpy.
  • db.schema: database schema. Default kinton.
  • host address of the database. Default localhost.
  • db.port: port where the database is listening. Default 3306.
  • redis.pass: Redis database password. Default empty.
  • Redis database host. Default localhost.
  • redis.port: Redis database port. Default 6379.
  • passwd.path: path to the seed file. If not provided a default seed will be used. Default empty.

For example, to update only local database with default port and schema, you will run:

# java -Ddb.update=true -Ddb.pass="" -Dpasswd.path=/etc/abiquo/.store -Xms128m -jar path/to/encryptor-1.0.0.jar

To update credentials on a Redis database which uses no password, you should run:

# java -Dredis.update=true -Dpasswd.path=/etc/abiquo/.store -Xms128m -jar path/to/encryptor-1.0.0.jar

Options specified as "-Dxxx" are Java properties, not command arguments, so they need to be specified before the jar file in the command line. If you place them after the jar file name, they will be interpreted as command parameters and will have no effect.

passwd.path option is very important. For all executions in the same environment the very same value must be used. If not Abiquo won't be able to operate.

4.9. Review client UI configuration

The client-config.json file is not changed during an Abiquo upgrade, so you will need to review this file.

Abiquo 3.1 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 the 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.

[root@api /]# cd /var/www/html/ui/config
[root@api config]# cp client-config.json client-config.json.old.3.0
[root@api config]# cp client-config.json.rpmnew client-config.json
[root@api config]# vim client-config.json

Change the API version to the current version so that the UI will use the current version of the API mediatypes.


You can verify this change by checking the UI calls to the API in the browser console.

Check that UI properties for new features are present in the file. For example, in Abiquo 3.1, the presets for load balancers are found in the config.loadbalancerprotocols section (see the following excerpt).

    "config.loadbalancerprotocols" : [
        {"value":"DNS_TCP", "protocol":"TCP", "port":53},
        {"value":"SSL", "protocol":"SSL", "port":443 }


4.10. Start the abiquo-tomcat service

service abiquo-tomcat start

4.11. Packages upgraded

The following packages are upgraded in Abiquo 3.1



5. Post upgrade

5.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. 

5.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

6. Release Notes for Abiquo 3.1