5 Upgrading to RUEI 5.1

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

5.1 Upgrading From RUEI 5.0.x to 5.1

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

Note:

Before proceeding with the upgrade, make a backup of your configuration. This is necessary if you need to perform a rollback (described in Section 5.1.1, "Rolling Back to 5.0.x"). To do so, select System, then Maintenance, and then Backup and restore. The procedure is fully described in the Oracle Real User Experience User's Guide.

The upgrade procedure should not take longer than a few minutes. During this time, data collection is temporarily stopped. Note the upgrade procedure described below should be performed as the root user unless indicated otherwise.

Upgrading Accelerator Packages

If your RUEI installation makes use of accelerator packages (such as for Oracle E-Business Suite or Siebel), these must be upgraded at the same time as the RUEI system. Ensure you follow the sequence of steps described in the rest of this section.

Reporter Upgrade

Do the following:

Copy the RUEI distribution pack (Vxxx.zip) to the Reporter system root directory, and unzip it. Repeat the unzip action for all required accelerator packages. Issue the following commands:
```
cd /root
unzip Vxxx.zip
```
Note as of release 5.1, a stand-alone Java package is used to install the Java Runtime Environment (JRE), rather than the version built into the database. Install the version bundled with the RUEI distribution set by issuing the following commands:
```
cd /root/RUEI/Java
./jre-1_5_0_18-linux-amd64-rpm.bin
```
Note you are prompted to accept the Java licence agreement. You cannot continue until you have done so.
This installs the necessary Java software in the directory /usr/java/jre1.5.0_18. To make the install directory version independent, create a more generic symlink using the following command:
```
ln -s /usr/java/jre1.5.0_18 /usr/java/jre
```
Temporarily stop all processing by issuing the following commands:
```
su - moniforce
project -stop wg
```
Create a backup of the /etc/ruei.conf file (as the root user), replace this file with the example supplied in the distribution pack, and make this configuration file readable to the moniforce user by issuing the following commands:
```
mv /etc/ruei.conf /etc/ruei.conf.50.backup
cp /root/RUEI/extra/ruei.conf /etc/
chmod 644 /etc/ruei.conf
chown moniforce:moniforce /etc/ruei.conf
```
Upgrade the RUEI Reporter RPMs by issuing the following commands:
```
cd /root/RUEI/51/
rpm -Uhv ux-*
```
Enable additional fonts for PDF generation. Because the PDF generator uses Java libraries, these need to be made available to Java. Copy (or move) the RUEI included fonts to the appropriate Java directory. For example:
```
cp /opt/ruei/gui/include/bi_publisher/fonts/* \
/usr/java/jre/lib/fonts/
```
Restart the Apache Web server by issuing the following command:
```
service httpd restart
```
Restart processing by issuing the following commands:
```
su - moniforce
project -start wg
```

The procedure for upgrading the Reporter system is complete.

Collector(s) Upgrade

Do the following:

Copy the RUEI distribution pack (Vxxx.zip) to the Collector system root directory, and unzip it. Repeat the unzip action for all required accelerator packages. Issue the following commands:
```
cd /root
unzip Vxxx.zip
```
Remove the line containing the entry /home/oracle/bin/ruei-clean.sh from Oracle's crontab file by issuing the following commands:
```
su - oracle
crontab -e
```
Stop the Oracle database, and remove the installation script so that it will no longer be started after a reboot, by issuing the following commands:
```
service oracledb stop
rm /etc/init.d/oracledb
```
Stop the Apache Web server by issuing the following commands:
```
service httpd stop
chkconfig --del httpd
```
De-install all RUEI RPMs (except ux-collector) by issuing the following command:
```
rpm -qa| grep ^ux-*-5.0* | grep -v ^ux-collector | xargs rpm -e
```
Create a backup of the /etc/ruei.conf configuration file, and replace it with the example contained in the distribution pack, by issuing the following commands:
```
mv /etc/ruei.conf /etc/ruei.conf.50.backup
cp /root/RUEI/51/extra/ruei.conf /etc/
```
Upgrade the Collector RPM by issuing the following commands:
```
cd /root/RUEI/51/
rpm -Uhv ux-collector-*
```

Repeat the above procedure for each Collector.

5.1.1 Rolling Back to 5.0.x

This section describes the procedure to rollback to version 5.0.x after upgrading to version 5.1.

Important:

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

Do the following:

Stop all RUEI processing by issuing the following commands:
```
su - moniforce
project -stop wg
```
Restore the backup of the /etc/ruei.conf file (as the root user) you created at the start of the upgrade procedure by issuing the following commands:
```
mv /etc/ruei.conf /etc/ruei.conf.51.backup
cp /etc/ruei.conf.50.backup /etc/
```
Downgrade the RUEI Reporter RPMs using the following commands:
```
rpm -e ux-wlp
cd /root/RUEI/50/
rpm -Uhv --oldpackage ux-*
```
Restart the Apache Web server by issuing the following command:
```
service httpd restart
```
Restart RUEI processing by issuing the following commands:
```
su - moniforce
project -start wg
```

Troubleshooting Rollback Problems

The rollback script ruei-rollback-5.0-5.1.sh logs its actions in the file /tmp/ruei-rollback-5.0-5.1.log. If you encountered any problems during the rollback, please attach this file to any request to Customer Support.

5.2 Upgrading From RUEI 4.5.x to 5.1

This section describes the procedure for upgrading an existing RUEI 4.5.x installation to release 5.1. For information on upgrading to RUEI 5.1 from a release prior to 4.5.x, please contact Customer Support.

The upgrade procedure needs to be performed on the Reporter system, as well as all required Collector systems. All actions must be performed by the root user. Be aware that when RUEI processing is stopped during the upgrade procedure, system notification alerts may be generated. These can be safely ignored.

Important:

Before proceeding with the upgrade, make a backup of your configuration. This is necessary if you need to perform a rollback (described in Section 5.2.2, "Rolling Back an Upgrade"). To do so, select System, then Maintenance, and then Backup and Restore. The procedure is fully described in the Oracle Real User Experience Insight User's Guide. In addition, it is strongly recommended you carefully review the information in Section 5.2.1, "Differences Between 4.5.x and 5.x" before performing an upgrade.

RPM Dependencies

Be aware that the 4.5.x RPMs do not contain dependency information. Therefore, you should ensure that all dependency RPMs listed in Section 3.3, "Installing the Database Prerequisites" are installed before starting the upgrade procedure described in this rest of this section.

Upgrading Accelerator Packages

Upgrading the RUEI System

The information in this section should be reviewed carefully before beginning the upgrade of the RUEI system and any required accelerator packages.

Note:

Currently, any defined password security policies are not applied until user logon. For this reason, it is recommended you carefully review all defined users and password security policies. In addition, you should remove all disabled user accounts prior to upgrade.

When upgrading, ensure all steps are performed in the following sequence:

If you need to need to upgrade your accelerator packages, login to the Reporter system 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.zipcd RUEI/extra
chmod +x ruei-upgrade-4.5-5.1.sh
```
Stop all processing by issuing the following command:
```
./ruei-upgrade-4.5-5.1.sh stop_ruei
```
RUEI 5.1 will be installed in the directory /opt/ruei, while configuration and log files are stored in the directory /var/opt/ruei. Before upgrading to the new RPMs, a number of environment changes need to be made. These are performed by the upgrade script using the following command:
```
./ruei-upgrade-4.5-5.1.sh rpm_pre_install
```
Before upgrading, obsolete versions of the Oracle Instant Client and PHP RPMs need to be uninstalled. To do so, use the following commands:
```
rpm -e php-oci8
rpm -e oracle-instantclient-sqlplus
rpm -e oracle-instantclient-basic
rm -rf /usr/lib/oracle/11.1.0.1
```

Install the new versions of the Oracle Instant Client RPMs using the following commands:

cd /root/RUEI/IC/rpm -Uhv oracle-instantclient11.1-*cd /root/RUEI/PHP/rpm -Uhv php-oci8-11gR1-*

Install the additional required RPMs using the following commands:
```
cd /mnt/dvd/Server
rpm -Uhv php-ldap-* \
lm_sensors-2.10.7-*.el5.x86_64.rpm \
net-snmp-5.3.2.2-*.el5.x86_64.rpm \
net-snmp-utils-5.3.2.2-*.el5.x86_64.rpm
```
Note:
If you upgrade your PHP installation (for example, using Yum), this can overwrite changes you previously made to the /etc/php.ini file. Therefore, you should be prepared to re-install the Zend Optimizer.
Copy the /etc/ruei.conf file included in the RUEI distribution pack.

Ensure the file is readable by the moniforce user by issuing the following command:
```
chmod 644 /etc/ruei.conf
```
A new PDF writer is introduced in this RUEI version, and it needs to be made available to the Apache daemon. Within the /etc/sysconfig/httpd file, remove the lines containing the LD_LIBRARY_PATH and TNS_ADMIN path settings, and replace with the following line:
```
source /etc/ruei.conf
```

Create the following PHP settings in the /etc/php.d/ruei.ini file:

session.gc_maxlifetime = 14400
memory_limit = 96M
upload_max_filesize = 128M
post_max_size = 128M

Note as of release 5.1, a stand-alone Java package is used to install the Java Runtime Environment (JRE), rather than the version built into the database. Install the version bundled with the RUEI distribution set, and make the installation directory version independent by issuing the following commands:
```
cd /root/RUEI/Java
chmod +x ./jre-1_5_0_18-linux-amd64-rpm.bin
./jre-1_5_0_18-linux-amd64-rpm.bin
ln -s /usr/java/jre1.5.0_18 /usr/java/jre
```
At this point, installation of the RUEI software begins. Go to the directory containing the application files, and install the associated RPMs. Use the following command:
```
rpm -Uhv ux-*
```
On the Reporter system, and each required Collector system, convert all SSL keys to the new required format by using the following command:
```
./ruei-upgrade-4.5-5.1.sh convert_sslkeys
```
For each required SSL, the script will ask you to specify and confirm the 4.5.x activation password, and a key passphase. If the SSL key has been installed without a passphase, this should be left blank.
Repeat steps 1 - 10 for each Collector system.
Enable additional fonts for PDF generation. Because the PDF generator uses Java libraries, these need to be made available to Java. Copy (or move) the RUEI included fonts to the appropriate Java directory. For example:
```
cp /opt/ruei/gui/include/bi_publisher/fonts/* \
/usr/jave/jre/lib/fonts/
```
Upgrade certain administrative information using the following command:
```
./ruei-upgrade-4.5-5.1.sh rpm_post_install
```
Re-initialize the database using the following command:
```
./ruei-upgrade-4.5-5.1.sh reinitialize
```
Because the storage of failed hits, pages, and services has changed in 5.0, they need to be converted using the following command:
```
./ruei-upgrade-4.5-5.1.sh convert_rolling_cubes
```
This may take several minutes. Any warnings generated by the script can be safely ignored.
Re-start RUEI using the following command:
```
./ruei-upgrade-4.5-5.1.sh start_ruei
```
Re-start the Apache Web server using the following command:
```
/etc/init.d/httpd restart
```
If you require multiple-byte character set support, issue the following command to install all optional fonts. Alternatively, install the multi-byte character sets necessary to meet your NLS requirements.
```
cd /mnt/dvd/Server
rpm -Uhv fonts-*
```
If you customized the logo shown in the top-hand corner of the dashboard, you will need to upload the required graphics file. The procedure to do this is fully explained in the Oracle Real User Experience Insight User's Guide.

Troubleshooting Upgrade Problems

The upgrade script ruei-upgrade-4.5-5.1.sh logs its actions in the file /tmp/ruei-upgrade-4.5-5.1.log. If you encountered any problems during the upgrade, please attach this file to any request to Customer Support.

Note:

Be aware that any 4.5.x backup you previously created cannot be used after your system has been upgraded to version 5.1. Therefore, it is recommended you create a 5.1 backup after completion of the upgrade procedure.

5.2.1 Differences Between 4.5.x and 5.x

This section highlights a number of reporting differences you may notice between versions 4.5.x and 5.x. Note an overview of all functional changes introduced in version 5.0 is available in the Release Notes, and the Oracle Real User Experience Insight User's Guide contains a complete description of all available functionality.

Session Diagnostics

In version 4.5.x, URL strings were reported in their raw format. For example, /doc/My%20Document.html. In 5.0, URL-encoded bytes are removed, and URL strings are formatted. For example, the previous URL would now be reported as /docs/My Document.html. Note how the %20 part is replaced by a space character. In addition, any NLS character encoding (such as Chinese) is now used to report the URL, rather than its URL- encoded form. There is one exception to this: the special characters /, ?, ;, %, =, and #, when present in the encoded form, are not decoded, but left "as is".

In order to minimize disruption, the upgrade procedure creates a new filter, based on the existing 4.5.x filter, for each defined filter. Hence, after upgrading, you will notice there are two filters: the 4.5.x filter will be applicable to the legacy 4.5.x data, and 5.0 filters will be used for monitoring 5.0 data. It is recommended you review all KPIs, SLAs, and reports that include URL-based definitions (such as filters or requirements). You are free to delete the 4.5.x filters whenever you decide 4.5.x data no longer needs to be reviewed.

URL Arguments

The handling of URL arguments within applications and custom dimensions definitions, as well as user ID matching, has also changed in 5.0.

Each URL argument has a name=value combination. In 4.5.x, the name part was decoded by RUEI. Therefore, all URL argument names had to be specified in their formatted version. For example, foo$bar$baz. In 5.0, URL argument names are no longer decoded, but reported in their raw (original) form. Therefore, they must also now be specified in their raw form. For example, foo%24bar%24baz.

Note the upgrade procedure automatically converts all URL argument name definitions to the new format. Therefore, it is not necessary to manually update them. However, be aware the reporting of these URL argument names will appear different in 5.0.

Conversion of Monitored Strings

The functionality that allows you to monitor strings that appear on pages (such as functional errors and page content checks) has changed in 5.0. All defined strings are automatically converted to their Unicode (UTF-8) equivalent.

Enriched Data Exchange Facility

The Enriched data exchange facility enables the alternative analysis of the data collected by RUEI. In particular, it allows you to combine the data collected by RUEI with other warehouse data. For example, a Customer Relationship Management (CRM) or Business Intelligence (BI) system. The exported data is based on pageviews, and is in XML format.

The XSD file that defines the structure of the exported XML files has changed in 5.0. Therefore, If you have systems that use data derived from the 4.5.x Enriched data facility, you will need review the new XML structure, and modify the operation of these systems as necessary. The Enriched data exchange facility is fully described in the Oracle Real User Experience Insight User's Guide.

5.2.2 Rolling Back an Upgrade

This section describes the procedure to rollback to version 4.5.x after upgrading to version 5.1.

Important:

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

Login to the Reporter system 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.zipcd RUEI/51
chmod +x ./ruei-rollback-5.1-4.5.sh
```
Run the ruei-rollback-5.1-4.5.sh script as root. This script performs all necessary rollback actions not covered by the RPM replacement.
Stop all RUEI processing by issuing the following command:
```
./ruei-rollback-5.1-to-4.5.sh stop_ruei
```
In RUEI 5.0, the product is installed in the directory /opt/ruei, while configuration and log files are stored in the directory /var/opt/ruei. Before downgrading to the old RPMs, a number of environment changes need to be made. These are performed by the downgrade script using the following command:
```
./ruei-rollback-5.1-4.5.sh rpm_pre_install
```
Edit the /etc/sysconfig/httpd file, and deleting the line referring to /etc/ruei.conf, and adding the following lines:
```
export LD_LIBRARY_PATH=/usr/local/instantclient/lib
export TNS_ADMIN=/home/moniforce
```

Downgrade the RUEI software using the following commands:

rpm -e ux-wlp
cd /root/RUEI/45
rpm -Uhv --oldpackage ux-*

Remove the new versions of the Oracle Instant Client and PHP RPMs using the following commands:

rpm -e oracle-instantclient11.1-sqlplus
rpm -e oracle-instantclinet11.1-basic
rpm -e php-oci8-11gR1

Restore the previous versions of the Oracle Instant Client and PHP RPMs using the following commands:

cd /root/RUEI/IC
rpm -Uhv oracle-instantclient-basic-11.1.0.*.rpm
rpm -Uhv oracle-instantclient-sqlplus-11.1.0.*.rpm
cd /root/RUEI/PHP/
rpm -Uhv php-oci8-5.1.6-*

Restore symlinks to the Oracle Instant Client using the following commands:

mkdir -p /usr/local/instantclient
ln -fsv /usr/lib/oracle/11.1.0.1/client64/lib /usr/local/instantclient
ln -fsv /usr/lib/oracle/11.1.0.1/client64/bin /usr/local/instantclient

Repeat steps 1 - 8 for each Collector system.
Restore the backup of your 4.5.x configuration. You will need to copy the backup file to the Reporter system, and store it in a location the moniforce user can access, such as /tmp. Then run the following commands:
```
cd /root/RUEI/51
./ruei-rollback-5.1-4.5.sh restore_backup /tmp/backup.tar.gz
```
replacing /tmp/backup.tar.gz with the name and location of the required backup file.
Undo a number of conversion actions by issuing the following command:
```
./ruei-rollback-5.1-4.5.sh rpm_post_install
```
Re-start RUEI using the following command:
```
./ruei-rollback-5.1-4.5.sh start_ruei
```
Because SSL keys are migrated to a different storage method during the upgrade, but no downgrade procedure is available, you will need to re-implement your SSL keys. This is fully described in the Oracle Real User Experience Insight User's Guide.
Optionally, convert the storage of failed hits, pages, and services back to 4.5.x format using the following command:
```
./ruei-rollback-5.1-4.5.sh convert_rolling_cubes
```

Troubleshooting Rollback Problems

The rollback script ruei-rollback-5.1-4.5.sh logs its actions in the file /tmp/ruei-rollback-5.1-4.5.log. If you encountered any problems during the rollback, please attach this file to any request to Customer Support.