3 Upgrading to RUEI 11.1

This chapter describes the procedure for upgrading an existing RUEI 6.x installation to release 11.1. The post-installation configuration procedure is described in Chapter 4, "Configuring RUEI".

If the Linux DVD is not automatically mounted, use the following commands to mount it:

mkdir -p /mnt/dvd
mount /dev/dvd /mnt/dvd

Note:

In the rest of this chapter it is assumed that the Linux DVD is mounted on /mnt/dvd.

Troubleshooting Upgrade or Rollback Problems

The upgrade and rollback scripts log their actions in the files /tmp/ruei-upgrade-x.log and /tmp/ruei-rollback-x.log. If you encountered any problems during the upgrade or rollback, please attach the relevant file to any request to Customer Support.

XPath Support

As of version 11.1, support for the use of XPath queries has been extended to provide full XPath 1.0 functionality for content scanning. This has important implications when upgrading an existing RUEI installation.

The upgrade script reports all namespaces found in the current configuration. These must be explicitly defined upon completion of the upgrade process. Otherwise, your configuration will no longer work correctly.

In addition, be aware that XPath expressions executed against content that is not well-formed XHTML code can return different results than in previous versions. Therefore, it is strongly recommenced that you carefully review all XPath expressions used in your RUEI installation. For further information on XPath support, see the Oracle Real User Experience Insight User's Guide.

Upgrading From RUEI 6.x to 11.1

This section describes the procedure for upgrading from an existing RUEI 6.x installation to release 11.1.

Important:

Before proceeding with the upgrade, make a backup of your configuration. Select System, then Maintenance, and then Backup and restore. The configuration backup is required in case of a rollback.

Upgrading Accelerator packages

As of version 6.5.1, all supported accelerators are automatically installed as part of the Reporter installation procedure. Note that the use of some accelerators requires additional Oracle product licenses. You should ensure that you are licensed to use a product before configuring suites based upon it. For further information, please consult your Oracle representative.

Upgrading the Reporter System

The Reporter upgrade procedure described in this section applies to both single server installations as well as dedicated Reporter systems.

Do the following:

Login to the Reporter as root. Within the /root directory, unzip the RUEI zip file, and go to the directory containing the application files. Use the following commands:
```
cd /root
unzip Vxxxx.zip
```

Stop all processing on the Reporter and Collector system(s) using the following commands:

cd /root/RUEI/extra
chmod +x ruei-upgrade-6.x-11.1.sh
./ruei-upgrade-6.x-11.1.sh stop_ruei

Note that if you are upgrading from version 6.5.1 or 6.5.2, you should not perform this step, but continue at step 8.

Install the new Oracle Instant client by issuing the following commands:
```
cd /root/RUEI/IC
rpm -Uhv oracle-instantclient11.2-*
```
Install the new PHP OCI module by issuing the following commands:
```
cd /root/RUEI/PHP
rpm -Uhv php-oci8-11gR2-*  
```

Update the logical links by issuing the following commands:

ln -sf /usr/lib64/oracle/11.2/php-oci8/oci8.ini /etc/php.d/oci8.ini
ln -sf /usr/lib64/oracle/11.2/php-oci8/oci8.so /usr/lib64/php/modules/oci8.so

Note the use of the force (-f) option.

Update the /etc/ruei.conf configuration file to use the new Oracle Instant client. Replace the line

export INSTANTCLIENT_DIR=/usr/lib/oracle/11.1/client64

with the line

export INSTANTCLIENT_DIR=/usr/lib/oracle/11.2/client64

Restart the Apache Web server by issuing the following command:
```
service httpd restart
```
Perform the necessary pre-upgrade actions by executing the following commands:
```
cd /root/RUEI/extra
./ruei-upgrade-6.x-11.1.sh rpm_pre_install
```
Make the ruei-prepare.sh and ruei-check.sh scripts available to the Oracle user (for example, by extracting the RUEI distribution zip on the Oracle database) on the system where the database resides. Update the RUEI database instance by issuing the following commands as the Oracle user:
```
cd /root/RUEI/111
cp ruei-prepare-db.sh /home/oracle
cp ruei-check.sh /home/oracle
chmod +x /home/oracle/ruei-*.sh
su - oracle
export ORACLE_HOME=/u01/app/oracle/product/11.1.0/db_1^{Foot 1}
./ruei-prepare-db.sh
exit
```
Upon completion, you should again be the root user.
For each required Collector system, perform the steps indicated in the following section. Upon completion, proceed to step 11.

Install the new versions of the RPMs using the following commands:

cd /root/RUEI/111
chmod +x ruei-install.sh
./ruei-install.sh *.rpm

Perform the necessary post-upgrade actions by executing the following commands:
```
cd /root/RUEI/extra
./ruei-upgrade-6.x-11.1.sh rpm_post_install
```
This step should be performed only if you are upgrading from RUEI version 6.0.x. Otherwise, it should be skipped.

Important: if you do not perform the action described in this step, the currently defined Error Page Replay (EPR) and Full Session Replay (FSR) settings are applied for each monitored application. Depending on the number of monitored applications, and your previous settings, the amount of required disk space can significantly increase. For example, if data retention was set to 50 GB, and five applications are monitored by a Collector, the Collector will reserve up to 50 GB per application upon upgrading to this version (that is, a total Collector disk space of 250 GB).

If this would require too much disk space to be reserved on a Collector system, you can issue the following command to limit the total reserved disk space to its currently defined settings:
```
./ruei-upgrade-6.x-11.1.sh resize_replay_store
```
In this case, the total reserved disk space for each application becomes the current setting divided by the current number of applications. For example, if the current data retention setting was 100 GB, and there are currently 10 monitored applications, this would result in 10 GB of disk space being available for each application. Note that, if you choose to use the above command, it may result in the loss of existing (the oldest) replay data.

Restart processing using the following commands:

cd /root/RUEI/extra
./ruei-upgrade-6.x-11.1.sh reinitialize
./ruei-upgrade-6.x-11.1.sh start_ruei

Note:

During and after the upgrade procedure, if error or information messages appear in the event log (select System, then Status, and then Event log), you should mark them as read after completing the upgrade procedure, and monitor whether new messages are reported. In the event of re-occurring error messages, you should contact Customer Support.

Upgrading the Remote Collector System(s)

For each required remote Collector system, login as root. Within the /root directory, unzip the RUEI zip file, go to the directory containing the application files, and install the new versions of the RPMs. Do the following:

Unzip the RUEI distribution package using the following commands:
```
cd /root
unzip Vxxxx.zip
```

Upgrade the Collector RPMs using the following commands:

cd /root/RUEI/111
chmod +x ruei-install.sh
./ruei-install.sh collector

This step should be performed only if you are upgrading from RUEI version 6.0.x. Otherwise, it should be skipped.

Convert the Replay store by issuing the following commands:
```
cd /root/RUEI/extra
chmod +x ruei-upgrade-6.x-11.1.sh
./ruei-upgrade-6.x-11.1.sh convert_replay_store
```
Note:
The script may fail if there is no replay data on the system, or if executed twice.

Rolling Back to Version 6.5.x

This section describes the procedure to rollback to version 6.5.x after upgrading to version 11.1. Note that the Collector included in the Reporter installation is automatically rolled back during the described procedure. However, remote Collector systems must be individually rolled back. The procedure to do this is described later in this section.

Important:

Be aware that it may not be possible to restore your system to its exact state prior to upgrading. It is strongly recommended that you contact Customer Support before rolling back an upgrade.

Login to the Reporter system as root. Within the /root directory, unzip the RUEI 6.5.x distribution zip file, and go to the directory containing the application files. Use the following commands:
```
cd /root
unzip Vxxx.zip
```
Stop all processing on the Reporter system by issuing the following commands:
```
cd /root/RUEI/extra
./ruei-rollback-11.1-6.5.x.sh stop_ruei
```
This step only applies to rollback to version 6.5.0. Remove all unused accelerator packages. Use the following command to list all installed accelerators:
```
rpm -qa | grep ^ux-suites
```
Use the following command to remove any appropriate accelerator:
```
rpm -e ux-suites-name
```
where name is the appropriate accelerator.
Execute the RPM pre-installation phase by issuing the following command:
```
./ruei-rollback-11.1-6.5.x.sh rpm_pre_install
```

Restore the previous RPMs by issuing the following commands:

cd /root/RUEI/65
chmod +x ruei-install.sh
./ruei-install.sh *.rpm

Execute the post-installation script by executing the following command:
```
./ruei-rollback-11.1-6.0.x.sh rpm_post_install
```
Rollback all required remote Collectors (using the procedure described in the next section). Upon completion, continue to step 8. If your installation does not make use of a remote Collector, proceed directly to step 8.
Restore the RUEI configuration backup you created prior to upgrading by selecting System, then Maintenance, then Backup and restore, and then select Restore system from file.

Restart processing by issuing the following commands:

cd /root/RUEI/extra
./ruei-rollback-11.1-6.5.x.sh start_ruei

Rolling Back Remote Collector Systems

Do the following:

Login to the remote Collector system as root. Within the /root directory, unzip the 6.5.x distribution zip file, and go to the directory containing the application files. Issue the following commands:
```
cd /root
unzip Vxxx.zip
```

Restore the previous RPMs by issuing the following commands:

cd /root/RUEI/extra
chmod +x ruei-rollback-11.1-6.5.x.sh
cd /root/RUEI/65
chmod +x ruei-install.sh
./ruei-install.sh ux-collector-*.rpm

Upon completion for all required Collectors, return to step 8 above.

Rolling Back to Version 6.0.x

This section describes the procedure to rollback to version 6.0.x after upgrading to version 11.1. Note that the Collector included in the Reporter installation is automatically rolled back during the described procedure. However, remote Collector systems must be individually rolled back. The procedure to do this is described later in this section.

Important:

Be aware that it may not be possible to restore your system to its exact state prior to upgrading. It is strongly recommended that you contact Customer Support before rolling back an upgrade.

Login to the Reporter system as root. Within the /root directory, unzip the RUEI 6.0.x distribution zip file, and go to the directory containing the application files. Use the following commands:
```
cd /root
unzip Vxxx.zip
```
Important:
If your RUEI installation makes use of accelerator packages (such as Oracle E-Business Suite or Siebel), repeat the unzipping for all previously installed accelerator packages.

Stop all processing on the Reporter system by issuing the following commands:

cd /root/RUEI/extra
./ruei-rollback-11.1-6.0.x.sh stop_ruei
chmod +x ruei-rollback-11.1-6.0.x.sh
./ruei-rollback-11.1-6.0.x.sh convert_replay_store

Remove all unused accelerator packages. Use the following command to list all installed accelerators:
```
rpm -qa | grep ^ux-suites
```
Use the following command to remove any appropriate accelerator:
```
rpm -e ux-suites-name
```
where name is the appropriate accelerator.

Issue the following commands:

sqlplus system/<password>@uxinsight
SQL> alter tablespace USERS default nocompress;

Execute the RPM pre-installation phase by issuing the following command:
```
./ruei-rollback-11.1-6.5.x.sh rpm_pre_install
```
Restore the previous RPMs by issuing the following commands:
```
cd /root/RUEI/60
rpm -e ux-lang-zh_cn
chmod +x ruei-install.sh
./ruei-install.sh *.rpm
```
Note that errors reported during this step can be safely ignored. They will be resolved upon completion of step 8.
Execute the post-installation script by executing the following command:
```
./ruei-rollback-11.1-6.0.x.sh rpm_post_install
```
Rollback all required remote Collectors (using the procedure described in the next section). Upon completion, continue to step 9. If your installation does not make use of a remote Collector, proceed directly to step 9.
Restore the RUEI configuration backup you created prior to upgrading by selecting System, then Maintenance, then Backup and restore, and then select Restore system from file.

Restart processing by issuing the following commands:

cd /root/RUEI/extra
./ruei-rollback-11.1-6.0.x.sh start_ruei

Note:

The admin password needs to be reset using the set-admin-password script after rolling back to version 6.0.x.

Rolling Back Remote Collector Systems

Do the following:

Login to the remote Collector system as root. Within the /root directory, unzip the 6.0.x distribution zip file, and go to the directory containing the application files. Issue the following commands:
```
cd /root
unzip Vxxx.zip
```

Restore the previous RPMs by issuing the following commands:

cd /root/RUEI/extra
chmod +x ruei-rollback-11.1-6.0.x.sh
./ruei-rollback-11.1-6.0.x.sh convert_replay_store 
cd /root/RUEI/60
chmod +x ruei-install.sh
./ruei-install.sh ux-collector-*.rpm

Upon completion for all required Collectors, return to step 9 above.

Footnote Legend

Footnote 1: This line requires customization based on your database version and installation path.