Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.

Abiquo 5.0

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 22 Next »

Admin Guide 1. Abiquo: Upgrading

This section describes how to upgrade from any version of Abiquo 3.0.0-GA or 3.x version to the latest Abiquo version, ie. Abiquo 4.0.x.  

While Abiquo is still releasing new 3.10.x versions, you can also upgrade from any Abiquo 3.0.0-GA or 3.x version to the latest Abiquo 3.10.x version, following the instructions at  Upgrade Abiquo to 3.10.x  

Please contact Abiquo Support for further information.


Abiquo 4.0 upgrade

Please follow the upgrade instructions carefully.

For Abiquo 4.x the location of upgrade files has changed.

The Abiquo 4.0 update will create new tomcat and websockify users and configure them to run the corresponding services. You will need to manually change ownership on the appropriate filesystems as part of the upgrade.

Abiquo 4.0 runs on CentOS 7. Although Abiquo will maintain support for CentOS 6 for some time, Abiquo recommends that customers upgrade to CentOS 7 as soon as possible.

Changes to Branding in Abiquo v4.0

There are changes to branding in Abiquo 4.0. See Abiquo Branding Guide for details of how to upgrade branding.


AZURE ARM upgrade to Abiquo 4.0.1

Customers using Azure ARM must run the upgrade process for this feature near the end of the upgrade to Abiquo 4.0.1. Before you begin your upgrade to Abiquo 4.0.1, please contact Abiquo Support for more information at the upgrade process.


Before you begin, remember to:

  • Stop services
  • Check for queued jobs or conversions 
  • Perform a full backup

Note about UI configuration:

  • The upgrade will OVERWRITE lang_en_US.json. If you have custom labels or translations, back them up before the upgrade and add them afterwards as lang_xx_XX_custom.json
  • The upgrade deprecates any previous client-config.json. You must add the API endpoint (if the URL is different from the UI endpoint) and any other custom configuration to client-config-custom.json after the upgrade

See Prepare to Upgrade Abiquo

1. Upgrade packages on ALL servers

  1. Configure Repositories
    1. Remove previous repo packages

      yum remove 'abiquo-release*'
    2. If upgrading to a new major version, install repo package for destination major version

    This installs base and update repositories. Please locate the abiquo-release-ee package of your destination version and install it with the following command. This example is for the latest Abiquo major version of 4.0.

    yum localinstall http://mirror.abiquo.com/el6/4.0/os/x86_64/abiquo-release-ee-4.0.0-452.el6.noarch.rpm
  2. Update yum cache

    yum clean all && yum makecache
  3. Update abiquo packages

    yum update
  4. Enforce the use of new package configuration files and grant permissions to the 'tomcat' user. Starting from 4.0 (and even after an upgrade), the Abiquo server will no longer run as root. It will run as the "tomcat" user, so we need to make sure all required files have the right permissions.
    NOTE: If you have a MONOLITHIC SERVER do all of the following steps on the Monolithic server

    1. On Abiquo Server and Remote Services

      chown -R tomcat /opt/abiquo
    2. On the Remote Services with Appliance Manager and the V2V Server (i.e. Servers that mount the NFS repository)

      chown -R tomcat /opt/vm_repository
      chmod -R a+r /opt/vm_repository
    3. On the V2V server, ensure /etc/sysconfig/abiquo/ec2-api-tools contains the lines below depending of the CentOS version the server is running in. If the file does not exists, created it with the contents as described below:

      For CentOS 6
      export EC2_HOME=/opt/aws
      For CentOS 7

2. Update the main Abiquo database on the database server

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

abiquo-db [-h DB hostname] [-P DB port] [-u user] [-p password] update

There is a known issue with upgrades from 3.2 versions where the following message appears and the liquibase update fails: 

Liquibase update Failed: Validation Failed:
1 change sets check sum
src/X.X.X-XX/kinton-X.X.X.xml::ABICLOUDPREMIUM-XXXX-XxxxxxxxXXxXxxxxxxXxxxxx::XXXXXXXXX is now: 7:ee2fa6e058ec76c7abf801567898917d
For more information, use the --logLevel flag

This can be easily solved by executing the following command and retrying the abiquo-liquibase update command.

abiquo-db clearCheckSums


3. Upgrade additional elements for starting versions

Start with your original version and perform all the steps to the final version

All scripts are located on the Abiquo Server.

After you perform the yum upgrade, the script folder will depend on the version you are upgrading to.

Unless otherwise specified, when you upgrade to 3.x versions, the scripts are located in: /usr/share/doc/abiquo-server/redis and /usr/share/doc/abiquo-remote-services/redis/

When you upgrade to 4.x versions, the scripts are located in: /usr/share/doc/abiquo-redis/redis/

Under each folder there are a series of version folders, e.g. /usr/share/doc/abiquo-redis/redis/3.2.0

Before you run these version update scripts, change to the appropriate folder.

 Start here if you are upgrading from Abiquo 3.0

In 3.1 we introduced credentials encryption.

Install the new encryption libraries for Java 8

 Upgrade from Abiquo 3.1.x to 3.2.x#UpdateJCEencryptionlibraries

Upgrade from Abiquo 3.1.x to 3.2.x#UpdateJCEencryptionlibrariesTo cypher your current credentials, please follow these instructions:

 Upgrade from Abiquo 3.0.1 to 3.1#Encryptcurrentcredentials

Now continue with the sections for the following 3.x versions

 Start here if you are upgrading from Abiquo 3.1

If you starting your upgrade from 3.1, Abiquo 3.2 requires a new Java Cryptography Extension (JCE) libraries for Java 8 so you will need to install the new encryption libraries.

Upgrade from Abiquo 3.1.x to 3.2.x#UpdateJCEencryptionlibraries

Upgrade redis schema

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

 python /usr/share/doc/abiquo-model/database/src/redis/3.2.0/redis-delta-3.0_to_3.2.py

Note that in some previous versions these scripts were found in different locations on the Abiquo Server and Abiquo Remote Services nodes respectively but in any case they are the same scripts.

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

Now continue with the sections for the following 3.x versions

 Start here if you are upgrading from Abiquo 3.2

Execute this script on the Abiquo Management Server:

bash ./3.4.0/00-failed-templates.sh

And this other script on the Abiquo Remote Services:

bash ./3.4.0/01-old-vsm-definitions.sh

Now continue with the sections for the following 3.x versions

 Start here if you are upgrading from Abiquo 3.4

Execute this script on the Abiquo Management Server:

yum -y install python-redis
python ./3.6.0/02-null-creation-timestamp.py

And this other script on the Abiquo Remote Services:

yum -y install python-redis
bash ./3.6.0/00-old-vsm-definitions.sh
python ./3.6.0/01-vdc-provider-id.py

Now continue with the sections for the following 3.x versions

 Start here if you are upgrading from Abiquo 3.6

Execute these scripts on the Abiquo Remote Services:

python ./3.6.2/00-digitalocean-v2.py
bash ./3.6.4/00-old-vsm-definitions.sh

Upgrade monitoring server

Upgrade monitoring server

  1. On the monitoring server
    1. Install abiquo-release
      See #Upgrade packages on ALL servers
      • Note that there are no old abiquo-release packages on the monitoring server
    2. Install new modules

      yum install abiquo-delorean
      yum install abiquo-emmett
    3. Edit both monitoring configuration files and enter server details The files are delorean.conf and emmett.conf, which are found in the /etc/abiquo/watchtower directory. The following excerpt shows key properties in the configuration of BOTH configuration files: details of MySQL, KairosDB and RabbitMQ servers.  

      database {
       	url : "jdbc:mysql://dbserver.example.com:3306/watchtower", 
          username : "root",
          password : ""
      kairosdb {
          host : "kdbserver.example.com", 
          port : 8080
      amqp.rabbitmq {
          # The known broker host
          host : "rabbitmq.example.com",  
          # The known broker port
          port : 5672,
          # User name to use when connecting to the broker
          username : "abiquo",
          # Password to use when connecting to the broker
          password : "abiquo",
  2. On the Abiquo database server, import watchtower DB schema, which can be found on the monitoring server. Database watchtower must be created before importing it:

    mysql -e "CREATE DATABASE watchtower"
    mysql watchtower < /usr/share/doc/abiquo-watchtower/database/watchtower_schema.sql

    (In Abiquo 3.8.x: /usr/share/doc/abiquo-watchtower/database/src/watchtower-1.0.0.sql)

  3. On the Abiquo API and Remote Services servers, edit abiquo.properties to:
    1. Enable monitoring and set watchtower properties to point to watchtower server and port.

      abiquo.monitoring.enabled = true
      abiquo.watchtower.port = 36638
      abiquo.watchtower.host = IP address where watchtower modules (delorean + emmett) are installed
    2. Comment out or delete KairosDB properties

      # KairosDB configuration
      #abiquo.kairosdb.host =
      #abiquo.kairosdb.port = 9999

Upgrade MariaDB

The required version of MariaDB has changed in Abiquo 3.8. Perform the upgrade manually with the following steps.

(minus) Before you begin, create a full database backup.

# rpm --nodeps -ev MariaDB-server
# yum install MariaDB-server
# service mysql start
# mysql_upgrade

Configure upgraded core packages

On the Abiquo Server, after the upgrade of the abiquo-core package to use Tomcat 8, the new server.xml file is saved on the filesystem as server.xml.rpmnew in the directory /opt/abiquo/tomcat/conf by default.

-rw-r--r--. 1 root root   2744 Jan 26 15:16 server.xml
-rw-r--r--. 1 root root   2384 Feb 16 10:34 server.xml.rpmnew

Overwrite the old server.xml file so that the tomcat will start

mv server.xml.rpmnew server.xml

Set updated RabbitMQ credentials

On the Abiquo Server, the new version of RabbitMQ does not allow default user guest to connect from hosts other than localhost. When upgrading, you need to either grant the guest user permissions to connect from every host or create a specific user in RabbitMQ (needs administrator privileges) for Abiquo. In the latter case, you need to adjust properties in every Abiquo host abiquo.properties file. See Abiquo Configuration Properties#rabbitmq

After the upgrade, manually start RabbitMQ service

service rabbitmq-server start


Check configuration of noVNC

In Abiquo 3.8+, noVNC is now the integrated package for remote access (replacing TightVNC). Add the client configuration properties described in the post-upgrade configuration.

Run Redis database script

On Management server:

# bash ./3.8.0/00-old-vsm-definitions.sh

On Remote services server:

# bash ./3.8.0/00-old-vsm-definitions.sh
 Additional step for upgrading from 3.8.0 or 3.8.1 with Watchtower

If you are upgrading from Abiquo 3.8.0 or Abiquo 3.8.1 and you have a monitoring server (Watchtower), do these steps:

  1. Contact Abiquo Support to obtain migration tool
  2. Check that Abiquo and Watchtower are stopped
  3. Note the properties described in the following table for use in the the next step


    Kinton MySQL jdbc URL, something like jdbc:mysql://abiquo.example.com:3306/kinton

    kinton.userThe MySQL username for kinton database
    kinton.passThe MySQL password for kinton database
    wt.urlWatchtower MySQL jdbc URL, something like jdbc:mysql://abiquo.example.com:3306/kinton
    wt.userThe MySQL username for watchtower database
    wt.passThe MySQL password for watchtower database
  4. Run the Abiquo Watchtower migration jar

    java [properties] -jar index_wt_alarms-1.0.0.jar

    For example:


    java -Dkinton.url=jdbc:mysql://abiquo.example.com:3306/kinton -Dkinton.user=root -Dkinton.pass=rPassword -jar -Dwt.url=jdbc:mysql://abiquo.example.com:3306/watchtower -Dwt.user=root -Dwt.pass=rPassword -jar  index_wt_alarms-1.0.0.jar
 Start here if you are upgrading from version 3.8.3

The location of the scripts in this section depends of the destination Abiquo version. You have to replace DBuser and DBpassword with your environment DB credentials.

If you are upgrading to Abiquo 4.x or higher, execute this command first:

cd /usr/share/doc/abiquo-model/database/src

If you are not upgrading to Abiquo 4.x or higher, execute this command instead:

cd /usr/share/doc/abiquo-server/database/src

If you upgrade to Abiquo 3.8.4 or higher:

python 3.8.4/00-update-policy-def-from-metedata.py DBuser DBpassword

If you upgrade to Abiquo 3.8.5 or higher:

python 3.8.5/00-update-policy-def-from-metedata-ii.py DBuser DBpassword
 Upgrade to Abiquo 4.0

 Upgrade to Abiquo 4.0

  1. Run the Python delta to move backup results from metadata to the Abiquo database

    python /usr/share/doc/abiquo-model/database/src/4.0.0/00-move-backup-results-from-metadata.py
  2. If you are not using ROW format in your DB replication configuration, apply it with the following commands

    echo "binlog_format = ROW" >>/etc/my.cnf.d/replication.cnf
    service mysql restart
 Only customers using Azure ARM: Upgrade Azure ARM to Abiquo 4.0.1

Only for for customers using Azure ARM.

Run the upgrade process for the Azure ARM feature to upgrade to Abiquo 4.0.1.

Please contact Abiquo Support for more information.

 Step for upgrade from all versions

Upgrade the Watchtower schema on the Abiquo database server

  1. Check that Abiquo and Watchtower (abiquo-emmett and abiquo-delorean services) are not running

  2. Upgrade Watchtower schema

    watchtower-db [-h DB hostname] [-P DB port] [-u user] [-p password] update
  3. Bring up the watchtower services (preferably at the end of the upgrade after bringing up the Abiquo servers)

    service abiquo-delorean start
    service abiquo-emmett start


4. Configure Abiquo after the upgrade

  1. Before your start the Abiquo tomcat server, add Abiquo Configuration Properties to the abiquo.properties file. By default abiquo.properties is found in the /opt/abiquo/config/ folder.
  2. Configure the user interface. The default UI location in Abiquo 4.x is /var/www/html/ui.
    1. Optional: Add custom labels and translations in the lang_xx_XX_custom.json files in the lang folder
    2. Add custom configuration to client-config-custom.json. See Configure Abiquo UI

      If your API is not in the same domain as the UI, set the API endpoint pointing to your Abiquo API server

          "config.endpoint": "http://myAPIserver/api"

      Enter the IP and port of your remote access proxy for noVNC, for example:

      "client.remoteaccess.novnc.host": "",
      "client.remoteaccess.novnc.port": "41337",
  3. Check your remote access configuration. The standard configuration is described in Abiquo websockify proxy for noVNC
  4. Then do the steps in Install HAProxy after upgrade from 3.10.x to 4.0.x.
  5. Theme CSS files have changed their name, please rename your secure_theme.css files to theme.css
    (Warning: there are more changes to branding, please see the note at the top of the Abiquo Branding Guide page)

5. Start Abiquo server

Bring up the server and restart the HTTP daemon to refresh the user interface files.

service abiquo-tomcat start
service httpd restart
  • No labels