Upgrade Abiquo

This section describes how to upgrade from Abiquo 4.4.x or above to the current Abiquo 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 4.4 or above. To upgrade from earlier versions, please contact Abiquo Support

In Abiquo 4.7.x, you must upgrade Abiquo Reports to use the new events model. Please contact Abiquo Support for the file and procedure
In Abiquo 4.7.0, the data structure of the events streamed by the Outbound API (M module) has changed. Update data objects in your integrations. See Trace entity for a description of the new data entity
The database upgrade to Abiquo 4.7 may take a little longer than usual while changing the events format of past events.
In Abiquo 4.6 the "__EOF" label is mandatory at the end of each language file, otherwise the UI will not load correctly
Abiquo 4.5+ versions do not support CentOS 6
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.

1. Prepare branding upgrade

See Changes to branding for instructions on how to upgrade branding for the following versions:

4.5
4.6
4.6.1
4.7.0

In Abiquo 5.0, the new UI will require new branding. See Abiquo Branding Guide

2. Before the upgrade

Before you begin, remember to:

Stop services
- Remember to stop the following services on the Monitoring server: abiquo-delorean, abiquo-emmett, kairosdb, cassandra
Check for queued jobs or conversions
Perform a full backup

Known issue: Before the release of version 5.2.0, you must back up the `/etc/nginx/nginx.conf` of each Remote Services server where you have a configuration of the WebMKS feature enabled. The update will replace the content of the nginx.conf file with the default parameters. This issue has been documented in issue 13509.

See Prepare to Upgrade Abiquo for further details.

3. Upgrade packages on ALL servers

Check that you have the repository URL and credentials
To upgrade to a version with a patch number of zero, for example, version 5.0.0, version 5.1.0
Click here to show/hide steps to upgrade to a 0 version
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.1.0, the command would be similar to the following
  yum localinstall http://user:passwd@mirror.abiquo.com/el7/5.1/os/x86_64/abiquo-release-ee-5.1.0-6565.el7.noarch.rpm
4. Disable the updates repo. See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/sec-managing_yum_repositories
OR To upgrade to a version with patch number that is not zero, for example, version 5.1.1, version 5.1.2
Click here to show/hide steps to upgrade to a non-zero version
1. Disable the base repo
2. Enable the updates repo
See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/sec-managing_yum_repositories
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 https://www.oreilly.com/library/view/learning-the-bash/1565923472/ch01s09.html

Update Abiquo packages:

yum clean all && yum makecache && yum update 'abiquo-*'

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
```
EC2_HOME=/opt/aws
```

4. Update the Abiquo databases

Ensure your hostname is in your DNS or in your /etc/hosts file
To upgrade the Abiquo API databases, run the command below on the Server appliance:
```
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.
To upgrade the Abiquo Watchtower database, run the command below on the monitoring appliance:
```
watchtower-db [-h DB hostname] [-P DB port] [-u user] [-p password] update
```
Reporting changes: To upgrade the Abiquo Reports database for the upgrade to Abiquo 4.7.x+, contact Abiquo Support for the file and procedure.

5. Upgrade additional elements

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

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/00-old-vsm-definitions.sh

Upgrade from 4.4.x to 4.5x

Run additional database scripts

This is a new version of the same tool that was run in the 4.2.x to 4.4 upgrade. If you are upgrading from 4.2.x or earlier, you do not need to run this tool twice.

When upgrading from 4.4.x to 4.5, run the following tool that will generate two scripts.

Run the scripts after the database upgrade on the Abiquo kinton database server and the Watchtower database server.

The instructions for running the tool are at the following location:

/usr/share/doc/abiquo-model/scripts/watchtower_migration_tool/README.md

The tool is located at the following location:

/usr/share/doc/abiquo-model/scripts/watchtower_migration_tool/wttool.jar

Run tool to update VM naming on vCloud

Please contact Abiquo support.

Run Redis database script

On Remote Services server:

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/00-old-vsm-definitions.sh

Start here to upgrade from 4.5.x to 4.6.x

Nodecollector and cloud provider proxy changes

Discovery manage functions are now performed by the NARS remote service, which replaces the Nodecollector and Cloud Provider Proxy remote services.
As part of the upgrade process, administrators can remove the old remote service webapps: nodecollector and cpp.

Run Redis database script

On Remote Services server:

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/00-old-vsm-definitions.sh

Upgrade from 4.6.x to 4.7.x

Storage changes

If you have a custom external storage plugin, contact Abiquo Support to obtain the upgrade procedure: Upgrade a storage plugin to Abiquo 4.7
External storage in private cloud and public cloud is now managed using the NARS remote service, which replaces the Storage Manager. As part of the upgrade you can remove the ssm webapp

Run Redis database script

On Remote Services server:

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/00-old-vsm-definitions.sh

Reporting changes

To upgrade the Abiquo Reports database for the upgrade to Abiquo 4.7.x+, contact Abiquo Support for the file and procedure.

Post-upgrade step:

For VMs captured in a powered on state with Abiquo 4.6.3+ and vCenter 6.5+, the administrator can manually remove the VNC configuration from the VM definition file on the hypervisor to allow remote access without reconfiguring the VM. When WebMKS is enabled, users will then be able to connect to these VMs using the web console

Upgrade from 4.7.x to 5.0.x

Run Redis database script

On every Remote Services server:

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/00-old-vsm-definitions.sh

Post-upgrade steps:

Change the tutorials' softlinks in the frontend servers: if there is a softlink /var/www/html/ui/config/tutorials pointing to /opt/abiquo/config/tutorials, please change it to point to /opt/abiquo/tutorials instead.
If your Apache redirect addresses end in trailing slash characters ("/"), remove the trailing slashes

Upgrade steps from 5.0.x to 5.1.x

Run script to update job names on Veeam server

When upgrading from 5.0.x or 5.1.x to 5.1.2 or above, if you are using Veeam, run the following application that will update the job names on the Veeam server to allow duplicate VM names.

The instructions for running the tool are in the following file.

/usr/share/doc/abiquo-model/scripts/veeam-job-modifier/README.md

To run the tool, do these steps:

Edit the veeam.properties file and set the MySQL jdbc properties. Replace the examples with the values for the Abiquo database

abiquo.database.jdbcurl = jdbc:mysql://abiquoserver.example.com:3306/kinton
abiquo.database.user = mysqlUser
abiquo.database.password = mysqlPassword

Obtain the Veeam version and credentials to pass as arguments to the script
- veeam95u4 Run for usage with Veeam server 9.5u4 or veeam10 Run for usage with Veeam server 10
- -ip IP address of Veeam server
- -u, --user veeamServerUser
- -p, --password veeamServerPassword
The other argument defines a dry-run mode to test the script
- -no-dry, --no-dry-run If true, update Veeam job names. If false, only show what will the names will look like after the change

Run the tool in dry-run mode (with the argument "--no-dry-run false" and check the Veeam jobs that it will update.

java -jar /usr/share/doc/abiquo-model/scripts/veeam-job-modifier/veeam-job-modifier-jar-with-dependencies.jar veeam10 -ip \ http://veeamserver.example.com:9399/api -u veeamServerUser -p veeamServerPassword -no-dry false

Run the tool in production mode to update the Veeam server

java -jar /usr/share/doc/abiquo-model/scripts/veeam-job-modifier/veeam-job-modifier-jar-with-dependencies.jar veeam10 -ip \ http://veeamserver.example.com:9399/api -u veeamServerUser -p veeamServerPassword -no-dry true

After you run the tool, edit the veeam.properties file, and remove the temporary properties with the database credentials.

Run mandatory database scripts on Redis database and Watchtower SQL database

When upgrading from 5.0.x or 5.1.x to 5.1.2 or above, run the following tool that will generate two scripts to run on the Redis database and Watchtower SQL database. You can run the tool on any server that has an appropriate version of Java and as the script file is on the Abiquo Server, this may be the most convenient place to run it.

These scripts change the use of the Abiquo VM Identifier (name attribute) as the UID to the ID of the VM as the new UID.

The instructions for running the tool are in the following file:

/usr/share/doc/abiquo-model/scripts/wt-db-redis-db-migration-tool/README.md

To run the tool and scripts, do these steps:

On the Abiquo Server, run the tool to generate the scripts, supplying the database credentials for the APi
```
$ java -jar /usr/share/doc/abiquo-model/scripts/wt-db-redis-db-migration-tool/wtrtool.jar \
 --kinton "jdbc:mysql://localhost:3306/kinton?autoReconnect=true&user=mysqlUser&password=mysqlPassword" \
 --output .
```
You should find the following scripts in the output directory (by default the current directory)
- redisdelta, which is Bash script
- watchtowerdelta.sql
For each Remote Services server, copy the redisdelta Bash script to the server.
On every Remote Services server, run the Bash script. Note that this script requires Bash version 4, which is the default version on the Abiquo Servers
```
bash ./redisdelta
```
Copy the SQL script to the Watchtower Monitoring server.

Run the SQL script

mysql watchtower < ./watchtowerdelta.sql

Run Redis database script

On every Remote Services server:

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/00-old-vsm-definitions.sh

Upgrade steps from 5.1.x to 5.1.2 or greater

When upgrading from 5.1.0 or 5.1.1 to 5.1.2 or above, follow the steps from the Upgrade steps from 5.0.x to 5.1.x block.

6. Configure Abiquo after the upgrade

Before you 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. See Changes to Abiquo Configuration Properties
Configure the user interface. The default UI location in Abiquo 4.x 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"
}
```

7. Start Abiquo server and services

Bring up the server and restart the HTTP daemon to refresh the user interface files.
```
service abiquo-tomcat start
service httpd restart
```
Start the tomcat server on remote services
Start the monitoring services.
1. First start the cassandra service
```
sudo service cassandra start
```
2. Wait about 5 minutes until the service is up and running
3. Start the KairosDB service
```
sudo service kairosdb start
```
4. Wait about 1 minute until the service is up and running
5. Start the other services in this order
```
sudo service abiquo-emmett start
sudo service abiquo-delorean start
```