Abiquo 5.2

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 43 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

  • Base OS target for Abiquo 4.0 has changed from CentOS 6 to CentOS7.
    We will provide an upgrade path to Abiquo 4.0 from CentOS 6 based installations for some time, but we recommend that customers upgrade to CentOS 7 as soon as possible.
  • The Abiquo 4.0 update will create and configure new tomcat and websockify users to run the corresponding services. You will need to manually change ownership of files on the relevant filesystems as part of the upgrade.
  • Azure ARM upgrade to Abiquo 4.0.1: Run a separate 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
  • If you are using ESXi hypervisors, after the upgrade, log in to Abiquo and edit each hypervisor to enter the vCenter credentials
  • 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 to Abiquo 4.0.4 requires you to run a tool to encrypt VNC passwords

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.

1. Before the upgrade

Before you begin, remember to:

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

See Prepare to Upgrade Abiquo for further details.

2. Upgrade packages on ALL servers

  1. If you are upgrading to a newer major version, remove the previous version Abiquo release packages.

    yum remove 'abiquo-release-*'
  2. If you are upgrading to a newer major version, locate the corresponding abiquo-release-ee package and install it. For example, for Centos 6 Abiquo 4.0, use the command below:

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

    yum clean all && yum makecache && yum update 'abiquo-*'
  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 dependingof 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

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


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

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
sed -i 's/bc.period/bc.subtype/ 3.8.5/00-update-policy-def-from-metedata-ii.py

Run the following script to migrate backup metadata

python 3.8.4/00-update-policy-def-from-metedata.py DBuser DBpassword
python 3.8.5/00-update-policy-def-from-metedata-ii.py DBuser DBpassword
 Start here if you are upgrading from 3.10 versions

 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
  3. 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
 Only customers using Azure ARM: Upgrade Azure ARM to Abiquo 4.0.1

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

 Upgrade to Abiquo 4.0.2 and later 4.0.x versions

Upgrade to Abiquo 4.0.2

On the Abiquo server change the RabbitMQ configuration

  1. Delete all queues

    rabbitmqctl stop_app
    rabbitmqctl reset
    rabbitmqctl start_app
  2. Recreate the RabbitMQ user that you previously registered in Abiquo properties, for example, for the user abiquo:abiquo

    rabbitmqctl add_user abiquo abiquo
    rabbitmqctl set_user_tags abiquo administrator
    rabbitmqctl set_permissions -p / abiquo ".*" ".*" ".*"

On the Watchtower server, modify the RabbitMQ configuration for both modules.

Edit the delorean.conf AND emmet.conf to add the RabbitMQ addresses as a comma separated list of "host:port" addresses.

Here is a 3-line extract from a configuration file showing the new addresses property.

amqp.rabbitmq {
    # The rabbitmq addresses
    addresses : ["rabbitmq.example.com:5672"],

Remember to also change the abiquo.properties file on all servers.

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

Upgrade to 4.0.4

  • Avamar: edit properties as required

Encrypt VNC Passwords

You will find the vnc-encryptor tool on the server where you have the abiquo-model package installed, usually the database server or where you run your abiquo-db tool from:

java [Options] -jar /usr/share/doc/abiquo-model/scripts/vnc_encryptor/vnc-encryptor-1.0.0.jar

* db.user:      login credentials to database. Default _root._
* db.pass:      password to database. Default emtpy.
* db.schema:    database schema. Default _kinton_.
* db.host:      host address of the database. Default _localhost_.
* db.port:      port where the database is listening. Default _3306_.
* passwd.path   path to the seed. If not provided a default seed will be used. Default empty.
java -Ddb.pass=secret -Dpasswd.path=/path/to/.secret -jar /usr/share/doc/abiquo-model/scripts/vnc-encryptor-1.0.0.jar


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


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

    New obligatory properties in Abiquo 4.0.2

    • The  abiquo.m.instanceid property is obligatory and you must set a unique value for each instance of the outbound API, which includes each member of the same cluster of M nodes
    • The abiquo.rabbitmq.addresses property is obligatory. You must define a comma-separated list of host:port address values for your RabbitMQ server(s). Replaces the separate address and port properties, which are deprecated
  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)
  6. Abiquo 4.0.4: Custom email template for guest password emails: optionally modify the template to include the new fully qualified domain name variable (fqdn)

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

7. Post upgrade step for ESXi and vCenter

After you complete the upgrade, log in to Abiquo and edit each ESXi server.

Enter the details of the vCenter, such as the Manager IP address, user and password.

  • No labels