Skip to end of metadata
Go to start of metadata

This section describes how to upgrade from Abiquo 5.2.0 or above to an Abiquo 5.4.x version. 

Please contact Abiquo Support for further information.


Abiquo YUM repositories are no longer open, please contact Abiquo Support to obtain your credentials

This upgrade process starts from Abiquo 5.2.0 or above. To upgrade from earlier versions, please see Upgrade Abiquo

There is no upgrade path from NSX-V to NSX-T because VMware does not support this upgrade

  • The upgrade will overwrite lang_en_US.json. If you have customized labels or translations, back them up before the upgrade and restore them afterwards accordingly.
  • The upgrade will overwrite the SAML login configuration for multiple IdPs. If you use SAML with multiple IdPs, back up the configuration files before the upgrade and add the multiple IdPs afterwards accordingly. See Restore SAML security beans after upgrade

The upgrade to Abiquo 5.3 includes a migration to provider ID as the identifier of a deployed VM.

See Provider ID as VM identifier upgrade

Prepare the provider ID migration before your upgrade. See Create a test VM and run PIM planner on a database dump

Prevent cloud users from performing VM operations

  1. In the UI in the Infrastructure view, select each physical machine and click Disable
  2. Using the API, set the state of each physical machine to DISABLED

Check for operations in progress on the platform

Before you shut down the platform servers you should check that no operations are in progress.

Before you shut down the platform servers you should check that no operations are in progress on the platform.
  1. Check that the Abiquo RabbitMQ queues are empty on the Abiquo Monolithic Server, Abiquo Server or Datanode server

    The number of messages in all queues must be 0.

    # rabbitmqctl list_queues messages name
     Click here to show/hide more details
    # rabbitmqctl list_queues messages name
    Listing queues ...
    0	abiquo.bpm.notifications
    0	abiquo.datacenter.requests.ADatacenter.bpm
    0	abiquo.datacenter.requests.ADatacenter.virtualfactory
    0	abiquo.ha.tasks
    0	abiquo.nodecollector.notifications
    0	abiquo.pcrsync.messages
    0	abiquo.pcrsync.parking-expect-no-consumers
    0	abiquo.scheduler.requests
    0	abiquo.scheduler.slow.requests
    0	abiquo.tracer.traces
    0	abiquo.virtualfactory.notifications
    0	abiquo.virtualmachines.definitionsyncs
    0	abiquo.vsm.eventsynk
  2. On the V2V Server, check for any active conversions by checking for the V2V or Mechadora processes

    $ ps aux | grep v2v
    $ ps aux | grep mechadora

When users' VM operations are blocked and all of the above checks show that no tasks are running, it is safe to halt the platform.

Back up the main platform elements

To perform a basic backup of the platform, run the following backups:

Before you begin, stop platform services and check you have enough space on your destination systems

  1. Back up the Abiquo MySQL DBs with the date in timestamp format.

    mysqldump --routines --triggers kinton            > kinton.sql-$(date +%Y%m%d_%H%M%S)
    mysqldump --routines --triggers kinton_accounting > kinton_accounting.sql-$(date +%Y%m%d_%H%M%S)
  2. Dump the Redis datastore and back it up.

    redis-cli save
    cp -a /var/lib/redis /var/lib/redis-$(date +%Y%m%d_%H%M%S)
  3. Back up /opt/abiquo folder on all Abiquo platform servers.

    tar cvfz /opt/abiquo.tgz-$(date +%Y%m%d_%H%M%S) /opt/abiquo
  4. Back up the UI

    tar cvfz /var/www/html/ui.tgz-$(date +%Y%m%d_%H%M%S) /var/www/html/ui

Stop platform services

This section describes how to stop platform services on all servers.

if there are operations in progress, DO NOT STOP the platform services because this can cause serious issues with your platform.
See Check for operations in progress on the platform and wait for all operations to complete

To stop platform services:

  1. Stop the API on the API Server or Monolithic Server

    systemctl stop abiquo-tomcat
  2. Stop the UI on the API Server or Monolithic Server or dedicated UI Server

    systemctl stop httpd
  3. Stop Remote Services server

    systemctl stop abiquo-tomcat
  4. V2V Server
    You do not need to stop anything because the BPM remote service is run on-demand only

  5. Stop Monitoring server

    systemctl stop abiquo-delorean
    systemctl stop abiquo-emmett
    systemctl stop kairosdb
    systemctl stop cassandra
  6. On the Monitoring server, check if Cassandra is really dead

    ps auwx | grep cassandra

    Get the process number for Cassandra (the first number in the output of the previous command), and kill it. In this example, Cassandra is process 12345.

    kill -9 12345

All processes on platform servers should now be halted.

Make snapshots and backups of all platform servers

This is a major upgrade, so we recommend that you make a snapshot and/or a backup of your platform servers.

Prepare yum repositories for 5.4

  1. Check that you have the repository URL and credentials

  2. To upgrade to a version with a patch number of zero, for example, version 5.3.0

    1. Remove the previous version Abiquo release packages.

      yum remove 'abiquo-release-*'
    2. Locate the corresponding abiquo-release-ee package in the list of available versions

    3. Install the release package. For Abiquo 5.3.0, the command would be similar to the following

      yum localinstall
    4. Disable the updates repo. See

  1. Check that you have the repository URL and credentials

  2. To upgrade to a version with patch number that is not zero, for example, version 5.3.x, enable both repositories:

    yum-config-manager --enable abiquo-base
    yum-config-manager --enable abiquo-updates
  3. Optionally add your username and password to the Abiquo repos

    yum-config-manager --save --setopt=abiquo-*.username=MYUSERNAME
    yum-config-manager --save --setopt=abiquo-*.password=MYPASSWORD

    Don't forget to use a backslash to escape any shell special characters. For more details, see

  4. Clean yum and make cache

    yum clean all && yum makecache
  5. If you did not make snapshots of all servers already, then you could do this now.

Upgrade packages on ALL servers

These instructions are for monolithic, distributed, and HA environments.

  1. Update Abiquo packages:

    yum clean all && yum makecache && yum update 'abiquo-*'
  2. The Abiquo services must run as the tomcat user (not root), so set the required permissions and enforce the use of the package configuration files.
    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, check the /etc/sysconfig/abiquo/ec2-api-tools file exists.
      The file must contain the following configuration. If the file does not exist, create it and add this configuration.

      For CentOS 7

Update the Abiquo databases

  1. Check that your hostname is in your DNS or in your /etc/hosts file

  2. Upgrade the Abiquo API databases

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

    If the liquibase update fails with a message similar to the following: 

    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

    Do the following steps

    1. Clear the database checksums

      abiquo-db clearCheckSums
    2. Retry the above abiquo-db update command.
  3. To upgrade the Abiquo Watchtower database, on the monitoring appliance, run the command below:

    watchtower-db [-h DB hostname] [-P DB port] [-u user] [-p password] update
  4. Reporting changes: To upgrade the Abiquo Reports Server for the upgrade to Abiquo 5.3.x, contact Abiquo Support for more information.
    • The Abiquo Reports Server now runs with JasperReports v7.8.0

Perform the provider ID migration in an upgrade through 5.3 only

For an upgrade that passes through Abiquo 5.3, perform the provider ID migration using the PIM tools.

Run the PIM planner

The PIM planner connects to the Abiquo kinton database and extracts the data for the PIM migrator tool.
  • The PIM planner will process each deployed VM to:

    • Compute the provider ID
    • Define the rename of any backup jobs or groups
    • Define the rename of any firewalls and load balancers

The PIM planner doesn't make any changes to the platform but you must run it after you upgrade the database to Abiquo 5.3.

What is the output of the PIM planner?

  • A log in standard output (you should redirect it to a file)
  • A migration plan in ZIP format called

PIM planner requirements

The PIM planner requires access to the MariaDB kinton schema via the JDBC URL. 

  • It encrypts the database credentials for runtime use only; it does not save or export credentials

Before you run the PIM planner

  1. Start the Abiquo upgrade to 5.3 as usual including
    1. Stop the Abiquo platform
    2. Create backups including VM snapshots, Database dump, and Redis dump
  2. Upgrade the database
  3. STOP the upgrade

Run the PIM planner

To run the PIM planner do these steps.

  1. Run the Abiquo upgrade to 5.3 and stop after the database upgrade

  2. On the Abiquo API Server, install the Abiquo PIM tools package

    yum install abiquo-pim-tools

    By default, it should install in the /opt/abiquo/pim-tools folder

  3. Run the PIM planner against your database.

    We strongly reccommend that you redirect the log in the standard output of the PIM planner to a file.

    For example:

    java -jar /opt/abiquo/pim-tools/pimplanner.jar --jdbc-url="jdbc:mysql://my.database.server:3306/kinton?autoReconnect=true&user=root&password=root" | tee output_pimplanner.log
  4. Check the output file from the PIM planner
    (warning) If there are any warnings or errors, resolve them before you continue. 
    If you have any doubts, please contact Abiquo Support.
  5. For ALL Remote Services servers
    1. Copy the file to each Remote Services server
    Next, follow the instructions to run the PIM migrator on each Remote Services server
PIM planner options








Kinton JDBC URL including user and password




The output file. The default is ''

Run the PIM migrator

The PIM migrator performs the provider ID migration in the compute, backup, and networking providers via the Remote Services servers.
  • It updates the VMs, backups, firewalls, and load balancers in the providers and in Redis
  • It also tests the migration in dry run mode

What does it output?

  • An SQL file to run on the kinton database
  • A log in standard output (you should redirect it to a file)

PIM migrator requirements

The PIM migrator requires the following.

  • The migration plan from the PIM planner
  • Access to:
    • the Redis instance of the Remote Service server.
    • the hypervisors in the datacenter

Before you run the PIM migrator

Do these steps.

  1. Start the Abiquo upgrade to 5.3 as usual including
    1. Stop the Abiquo platform
    2. Create backups including snapshots, Database dump, and Redis dump
  2. Upgrade the database
  3. STOP the upgrade
  4. Run the PIM planner and obtain the migration plan

Run the PIM migrator

Do these steps to run the PIM migrator.

Before you run the PIM migrator on your production servers:

  1. you must run it in your lab environment
  2. you must run it in dry run mode with the migration plan from the PIM planner that you ran on a dump of your production database

Log in to ALL Remote Services Servers and do these steps on EACH server. 

  1. Install the PIM tools

    yum install abiquo-pim-tools

    The default install folder is /opt/abiquo/pim-tools

  2. Obtain the datacenter-id of the Remote Services server from the value of the property in the file.

    In this case, the value of the datacenter-id parameter will be "abq_dc1"

  3. Run the PIM migrator in dry run mode, which is the default mode that doesn't make any changes.

    The "-noseed" parameter is required. The default value is false, which means the migrator will use the platform's default seed file. You can specify a seed file with the "-seed" parameter. 

    We recommend that you save the log in standard output to a file. And we recommend that you give the output files names that will identify the Remote Services server.

    For example 

    java -jar /opt/abiquo/pim-tools/pimmigrator.jar -dc=abq_dc1 -redishost=localhost -noseed -output=update_DC1.sql | tee pimmigrator_dry_run_DC1.log
  4. Check the output file. If there are any errors or warnings, resolve them.
    If necessary, contact Abiquo Support.
  5. Run the PIM migrator in update mode, by setting the "no dry run" option to true.

    java -jar /opt/abiquo/pim-tools/pimmigrator.jar -nodry -dc=abq_dc1 -redishost=localhost -noseed -output=update_DC1.sql | tee pimmigrator_DC1.log
  6. Copy the SQL file from the Remote Services server to the Abiquo database server.

    For example

    scp update_DC1.sql root@my.database.server:~/

After you run the migrator on ALL Remote Services servers, run the SQL upgrades on the database server as described in the next step. 

Update the Abiquo database server

  1. Update the Abiquo database with all of the update.sql files. For example

    mysql kinton < update_DC1.sql
    mysql kinton < update_DC2.sql

Now continue with the Abiquo upgrade

PIM migrator options








ID of the current datacenter to migrate




Set to 'true' in order to perform the changes (default: false)




If true, don't use a seed file and ignore the seed property value (default: false)




SQL output file (by default 'update.sql')




Migration plan data file




Redis server host for this datacenter




Redis server port for this datacenter (by default 6379)




Seed file (by default '/etc/abiquo/.store')

PIM migrator notes

The migrator does not process the following providers.

  • Hyper-V
  • Networker
  • Google Cloud Platform (see note below)
  • Firewalls and load balancers that are not in NSX

For Google Cloud Platform, if you have VMs deployed before the upgrade, after you apply the PIM tools, do these steps:

  1. Delete the VMs from the platform only 
    • in the API, delete them with the "logicaldelete" parameter set to true. See Delete a VM API doc 
  2. Delete the virtual datacenters
  3. Onboard the resources again

Upgrade additional elements

By default, you will find the upgrade scripts (e.g. for Redis definitions) on the Abiquo Server under the folder: /usr/share/doc/abiquo-redis/redis/

For each upgrade step, run the Redis database script to remove old VSM definitions, which can be found in the 4.2.3 subfolder

On Remote Services server:

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/

If you have custom billing queries, please update them now.

 Click here to show/hide the steps to upgrade from 5.2.0 or higher to 5.3.x

Run Redis database script
(tick) These scripts can always be found on the Abiquo Server.
On each Remote Services server (including Monolithic sever) or Datanode server run the Redis scripts

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/

 Click here to show/hide the steps to upgrade from 5.3.0 or higher to 5.4.x

Run Redis database script
(tick) These scripts can always be found on the Abiquo Server.
On each Remote Services server (including Monolithic sever) or Datanode server run the Redis scripts

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/

Configure Abiquo after the upgrade

  1. Before you start the Abiquo tomcat server, add Abiquo Configuration Properties to the file.
    By default the file is found in the /opt/abiquo/config/ folder.
    See Changes to Abiquo Configuration Properties

  2. Configure the user interface. The default UI location is /var/www/html/ui.
    Optional: Add custom labels and translations in the lang_xx_XX_custom.json files in the lang folder
    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"
  3. SAML: If you are using SAML with multiple IDPs, restore the configuration as described at Restore SAML security beans after upgrade.

  4. Reporting changes: To upgrade the Abiquo Reports Server for the upgrade to Abiquo 5.3.x, contact Abiquo Support.

Start Abiquo server and services

To start the Abiquo platform servers and services, do these steps:

  • On the Abiquo Server, restart the HTTP daemon to refresh the user interface files, and bring up the Tomcat server.

    service httpd restart
    service abiquo-tomcat start
  • On the Remote Services server, start the Tomcat server

    service abiquo-tomcat start
  • On the Monitoring Server, start the Cassandra service

    sudo service cassandra start
  • WAIT about 5 minutes until the service is up and running
  • Start the KairosDB service

    sudo service kairosdb start
  • WAIT about 1 minute until the service is up and running. If the startup process fails and there are entries in the log file `/opt/kairosdb/log/kairosdb.log` that look like this "Unable to setup cassandra schema com.datastax.driver.core.exceptions.NoHostAvailableException: All host(s) tried for query failed", then:

    • Edit the file /opt/kairosdb/conf/ .
    • Replace the line kairosdb.datastore.cassandra.host_list=192.168.888.999:9160 .
    • With this line kairosdb.datastore.cassandra.cql_host_list=192.168.888.999 . Please note the new cql_ preffix for this property.
    • Remove this property from /etc/cassandra/conf/cassandra.yml "kairosdb.datastore.cassandra.datapoint_ttl" and add it on /opt/kairosdb/conf/ Set it to 15768000. [ref: Internal JIRA SUP-333]
  • Start the other services in this order

    sudo service abiquo-emmett start
    sudo service abiquo-delorean start