Specific Version Upgrade Notes

Upgrading from versions 2.8.2010.2 and up to 2.8.2110.2

Upgrade Kiuwan to run in unprivileged mode

Please proceed further if you want to upgrade Kiuwan to run as a non-root user. Please note that these steps stop Kiuwan services for upgrade.

Step 1: Stop all the services

The purpose is to gracefully shut down the services for upgrade. Change the directory to [INSTALLER_DIR] and execute

sudo ./stop-all.sh

Step 2: OS and Docker configuration

Execute step 1 from Installation: common steps section.

Step 3: Set the right permissions for the non-root user

1. Set ownership and permissions to the volumes directory sudo

   chown -R steve:steve [VOLUMES_DIR]/ sudo chmod -R 777
   
   [VOLUMES_DIR]/config-shared/MySql/ sudo chmod -R 777
   
   [VOLUMES_DIR]/data-local/MySql/

2. Set ownership and permissions to the installed directory

   sudo chown -R steve:steve [INSTALLED_DIR]/

   The steps below are to be run as the non-root user.

Step 4: Update the globalConfig.properties

Edit the following properties under the section named "Kiuwan instances shared configuration" for the configuration file present at [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

1. Set kiuwan.ownNamespaceEnabled=true
2. Set kiuwan.accessMySql=true if you want to enable access to MySql port. Default value is false. This can be enabled later on after the upgrade, separately if you are unsure right now.

Step 5: Clear the redis node configuration

Clear the redis nodes.conf and corresponding backup files present in the below locations.

rm [VOLUMES_DIR]/data-local/Redis/data/6379/nodes.conf* rm

[VOLUMES_DIR]/data-local/Redis/data/6380/nodes.conf* rm

[VOLUMES_DIR]/data-local/Redis/data/6381/nodes.conf* rm

[VOLUMES_DIR]/data-local/Redis/data/6382/nodes.conf* rm

[VOLUMES_DIR]/data-local/Redis/data/6383/nodes.conf* rm

[VOLUMES_DIR]/data-local/Redis/data/6384/nodes.conf*

Step 6: Run installer

It is recommended to reboot the machine before running installer as it is observed intermittently that the docker containers are unable to access the external network to download images.

Change the directory to [INSTALLER_DIR] and execute these commands:

./deploy-user-content.sh
./install.sh

Step 7: Enable MySQL port (optional)

If you want to enable MySQL port access on the host machine after namespace is enabled. You need not run this if you had already set this property before running install.sh

• Set kiuwan.accessMySql=true in [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

Change the directory to [INSTALLER_DIR] and execute ./openMysqlPort.sh

Upgrading from versions 2.8.1910.7 and up to 2.8.2010.2

If you have currently installed Kiuwan On-Premises version 2.8.1910.1, you will need to follow this guide to adapt your Kiuwan On-Premises infrastructure to the latest version.

Due to changes in how Redis Cluster is created through the installation process, to keep your installation up to date with the latest infrastructure you will need to follow a different approach to perform a full upgrade from this version.

You will need both the kiuwan-cluster version you used to install 2.8.1910.1 and the latest available kiuwan-cluster (that can be downloaded here https://static.kiuwan.com/download/onpremise/kiuwan-cluster.tar.gz). We will refer to these locations:

• [INSTALLER_DIR_OLD]: where the old kiuwan-cluster version was untared.
• [INSTALLER_DIR]: where the new kiuwan-cluster version has been untared.

Note that if you are using AWS elasticache service to run Redis Cluster services you can ignore this section and follow the standard upgrade process.

Step 1: Wait for all enqueued analyses to end

Make sure there are no running analyses before continuing to the next step. You can check this in the System Administration Console:

1. Access Kiuwan On-Premises with sysadmin user.
2. Access the Analysis Administration option in the upper right dropdown menu.
3. Click on the Active Analyses button and check if the table shows any running or pending analysis.

If you are using an automation tool to launch Kiuwan analyses, make sure you pause the needed jobs so no more analyses enter your Kiuwan On-Premises queues.

Once there are no more active analyses, you should wait for the pending analyses to be completely freed before stopping the Kiuwan server. This should take up to 30 minutes maximum.

Step 2: Stop kiuwan services

Change the current directory to the old kiuwan-cluster docker scripts and stop all the Kiuwan On-Premises services:

cd [INSTALLER_DIR_OLD]/docker
sudo ./stop-kiuwan.sh

This will stop all Kiuwan frontal, analyzer and schedulers containers currently running.

Step 3: Update your current configuration

To update the current Kiuwan On-Premises clients and your volumes global configuration file, you should run the update script located in the new kiuwan-cluster:

cd [INSTALLER_DIR]/docker
sudo ./update.sh

Step 4: Stop remaining containers and prune

Pruning containers are needed to upgrade to this version safely. To do so, run the uninstall.sh script from the new kiuwan-cluster installation directory.

Note that this step will NOT remove any data from your current installation:

cd [INSTALLER_DIR]
sudo ./uninstall.sh

Step 5: Clean Redis cluster data

Redis Cluster current data must be cleaned up to start a new, fresh cluster. Run the following command:

sudo rm -rf [VOLUMES_DIR]/data-local/Redis/data

Step 6: Update Redis cluster node information

Redis Cluster default configuration has been changed in later versions of Kiuwan On-Premises. If you are running the Redis provided service, you will need to update the Redis Cluster nodes locations.

Edit the global configuration file:

sudo vim [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties

You must change properties "redis.cache.nodes" and "redis.store.nodes" to these values:

redis.cache.nodes=172.17.0.1:6379,172.17.0.1:6380,172.17.0.1:6381,172.17.0.1:6382,172.17.0.1:6383,172.17.0.1:6384

redis.store.nodes=172.17.0.1:6379,172.17.0.1:6380,172.17.0.1:6381,172.17.0.1:6382,172.17.0.1:6383,172.17.0.1:6384

Step 7: Update your configuration

If you need to update any other configuration property, you can modify now any other configuration option. Changes will be taken into account when Kiuwan services are started in the next steps.

Please refer to Upgrading from version 2.8.1910.7 for details on how to modify your mail server configuration.

Please refer to Upgrading from versions 2.8.2010.2 for details on how to modify your Apache Load Balancer's httpd.conf configuration file.

Step 8: Run the install script for the new version

Running the installation script will recreate the new Redis Cluster and start all needed services:

cd [INSTALL_DIR]
sudo ./install.sh

Step 9: Continue with full upgrade steps

You can now continue with the standard full upgrade process just where you left it: Step 8: load balancer manual configuration (optional).

Upgrading from versions 2.8.1910.1 and up to 2.8.1910.7

Configuration changes were made to how the mail server is configured starting from version 2.8.1910.7. If you made manual changes in the Wildfly instances configuration to support TLS/SSL/plaintext based email servers, you must update your mail server configuration.

1. Edit the file [VOLUMES_DIR]/config-shared/globalConfig/globalConfig.properties
2. Look for the following properties:
   1. kiuwan.mail.authentication
   2. kiuwan.mail.username
   3. kiuwan.mail.password
   4. kiuwan.mail.secure.layer
   5. kiuwan.mail.secure.layer.value
3. Follow the instuctions found in the comments of each property or refer to Mail server configuration examples for details on how to set the value of each property.
4. Continue with Upgrading from versions 2.8.2010.2. Or if you are upgrading from 2.8.1910.1 you can skip this step.

Upgrading from versions before 2.8.1910.1

In Kiuwan On-Premise some of the underlying components have changed. In particular, the versions of the MySQL and REDIS containers were updated to the latest versions that are compatible with Kiuwan.

sudo ./stop-all.sh
sudo ./start-all.sh

Also, in this new version, the Apache HTTP server’s default configuration has changed. So, if you are upgrading from the previous version of Kiuwan On-Premises and you are using the embedded Apache HTTP server, please apply these changes manually in the next file:

[VOLUMES_DIR]/config-shared/ApacheLoadBalancer/conf/httpd.conf

If you are installing Kiuwan On Premises from zero, those changes do not need to be applied. Simply follow the standard installation procedure and skip the following.

These are the changes to apply:

• Enable mod_rewrite module loading:
  Before:
  # LoadModule rewrite_module modules/mod_rewrite.so
  After:
  LoadModule rewrite_module modules/mod_rewrite.so
  and add the next directives:

RewriteEngine On
RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK|OPTIONS) 
RewriteRule .* - [F]

Just after this group:

<IfModule ssl_module>
SSLRandomSeed startup builtin
SSLRandomSeed connect builtin
</IfModule>

• Add next directive:
  Header set X-Frame-Options: "SAMEORIGIN” 
  Inside next group: <IfModule headers_module>
  And this is the result:

<IfModule headers_module>
#
# Avoid passing HTTP_PROXY environment to CGI's on this or any proxied
# backend servers which have lingering "httpoxy" defects.
# 'Proxy' request header is undefined by the IETF, not listed by IANA
#
RequestHeader unset Proxy early
Header set X-Frame-Options:"SAMEORIGIN"
</IfModule>

• Replace the line:
  Require all granted
  by 
  Require all denied
  In this group:

<Directory
"/usr/local/apache2/cgi-bin">
AllowOverride None
Options None
Require all denied
</Directory>