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.


Documentation

Skip to end of metadata
Go to start of metadata

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 3.10.x version.  Please contact Abiquo Support for further information. And for upgrade to 4.x versions, please see Upgrade Abiquo

 

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 client-config.json. You must add the API 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
  2. 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 3.10.

    yum localinstall http://mirror.abiquo.com/abiquo/3.10/os/x86_64/abiquo-release-ee-3.10.0-1679.el6.noarch.rpm
  3. Update yum cache

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

    yum update 'abiquo-*' && yum update jdk

    If you are upgrading to a new major release, you should be updating all packages instead just Abiquo ones. Instead of the previous command run:

    yum update

2. Update the main Abiquo database on the database server

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

abiquo-liquibase [-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-liquibase clearCheckSums

 

3. Upgrade additional elements for 3.x versions

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

All scripts are located on the Abiquo Server

 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 RS nodes) to update the schema to the 3.2 version. This script can be found on following path on the Abiquo Server

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

And in the next path in the Abiquo Remote services

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

/usr/share/doc/abiquo-server/redis/3.4.0/00-failed-templates.sh

And this other script on the Abiquo Remote Services:

/usr/share/doc/abiquo-remote-services/redis/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 /usr/share/doc/abiquo-server/redis/3.6.0/02-null-creation-timestamp.py

And this other script on the Abiquo Remote Services:

yum -y install python-redis
/usr/share/doc/abiquo-server/redis/3.6.0/00-old-vsm-definitions.sh
python /usr/share/doc/abiquo-remote-services/redis/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 /usr/share/doc/abiquo-remote-services/redis/3.6.2/00-digitalocean-v2.py
bash /usr/share/doc/abiquo-remote-services/redis/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.  

      // ADDRESS WHERE MYSQL IS RUNNING - BY DEFAULT THE ABIQUO SERVER
      database {
       	url : "jdbc:mysql://dbserver.example.com:3306/watchtower", 
          username : "root",
          password : ""
      },
       
      // DETAILS OF KAIROSDB HOST
      kairosdb {
          host : "kdbserver.example.com", 
          port : 8080
      },
      
      // ADDRESS OF RABBITMQ (BY DEFAULT ABIQUO-SERVER)
      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",
      // MODIFY OTHER VALUES AS REQUIRED FOR YOUR SYSTEM
  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 = 10.60.11.24
      #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 /usr/share/doc/abiquo-server/redis/3.8.0/00-old-vsm-definitions.sh

On Remote services server:

# bash /usr/share/doc/abiquo-remote-services/redis/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

    PropertyDescription
    kinton.url

    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 versions between 3.8.2 and 3.8.5

Steps in the upgrade for 3.8.2 - 3.8.5

  1. Create Backup tables in database, replacing DBuser and DBpassword with your user and password

    python /usr/share/doc/abiquo-server/database/src/3.8.4/00-update-policy-def-from-metedata.py DBuser DBpassword
    python /usr/share/doc/abiquo-server/database/src/3.8.5/00-update-policy-def-from-metedata-ii.py DBuser DBpassword
 Start here if you are upgrading from version 3.10.4

Steps in the upgrade for 3.10.4 to 3.10.5

  1. On the Remote Services (or the server where you have installed Redis for the VSM) run the following command
 # bash /usr/share/doc/abiquo-remote-services/redis/3.10.5/00-old-vsm-definitions.sh
 Start here if you are upgrading from version 3.10.6

Steps in the upgrade for 3.10.6 to 3.10.7

  1. If you are using Avamar, upgrade the Avamar plugin and edit properties as required
  2. Contact Abiquo support to obtain the upgrade tool for VNC passwords. Run this tool after the upgrade, before you bring up the Tomcat server
  3. If you have a custom email template for guest password emails, optionally modify this template to include the new fully qualified domain name variable (fqdn)
  4. On the Remote Services (or the server where you have installed Redis for the VSM) run the following command
 # bash /usr/share/doc/abiquo-remote-services/redis/3.10.5/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

    abiquo-watchtower-liquibase [-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 restart the Abiquo tomcat servier, add Abiquo Configuration Properties to the abiquo.properties file. By default abiquo.properties is found in the /opt/abiquo/config/ folder.
    1. If you are using the OpenID integration, and you would like to retrieve the user phone number, add "phone" to the list of values of the abiquo.openid.client.scopes property
  2. Configure the user interface. The default UI location in Abiquo 3.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

      The essential UI configuration is 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

      "client.remoteaccess.novnc.host": "",
      "client.remoteaccess.novnc.port": "41337",
  3. Check your remote access configuration. The standard configuration is described here Abiquo websockify proxy for noVNC