Skip Headers

Oracle® Real User Experience Insight Installation Guide Release 5.1 for Linux x86-64 Part Number E14822-05 |
Home | Book List | Contents | Index | Contact Us

Previous | Next
| View PDF

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

1. Copy the RUEI distribution pack (`V` `xxx``.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

2. 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.

3. 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

4. Temporarily stop all processing by issuing the following commands:

       su - moniforce
       project -stop wg

5. 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

6. Upgrade the RUEI Reporter RPMs by issuing the following commands:

       cd /root/RUEI/51/
       rpm -Uhv ux-*

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

8. Restart the Apache Web server by issuing the following command:

       service httpd restart

9. 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:

1. Copy the RUEI distribution pack (`V` `xxx``.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

2. 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

3. 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

4. Stop the Apache Web server by issuing the following commands:

       service httpd stop
       chkconfig --del httpd

5. 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

6. 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/

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

1. Stop all RUEI processing by issuing the following commands:

       su - moniforce
       project -stop wg

2. 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/

3. Downgrade the RUEI Reporter RPMs using the following commands:

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

4. Restart the Apache Web server by issuing the following command:

       service httpd restart

5. 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

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.

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:

1. 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

2. Stop all processing by issuing the following command:

       ./ruei-upgrade-4.5-5.1.sh stop_ruei

3. 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

4. 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

5. 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-*

6. 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.

7. 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

8. 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

9. 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

10. 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

11. 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-*

12. 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.

13. Repeat steps 1 - 10 for each Collector system.

14. 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/

15. Upgrade certain administrative information using the following command:

        ./ruei-upgrade-4.5-5.1.sh rpm_post_install

16. Re-initialize the database using the following command:

        ./ruei-upgrade-4.5-5.1.sh reinitialize

17. Because the storage of failed hits, pages, and services has changed in 5.0, they need to be converted using the following command:

18.     ./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.

19. Re-start RUEI using the following command:

        ./ruei-upgrade-4.5-5.1.sh start_ruei

20. Re-start the Apache Web server using the following command:

        /etc/init.d/httpd restart

21. 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-*

22. 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.

1. 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

2. 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.

3. Stop all RUEI processing by issuing the following command:

       ./ruei-rollback-5.1-to-4.5.sh stop_ruei

4. 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

5. 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

6. Downgrade the RUEI software using the following commands:

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

7. 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

8. 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-*

9. 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

10. Repeat steps 1 - 8 for each Collector system.

11. 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.

12. Undo a number of conversion actions by issuing the following command:

        ./ruei-rollback-5.1-4.5.sh rpm_post_install

13. Re-start RUEI using the following command:

        ./ruei-rollback-5.1-4.5.sh start_ruei

14. 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.

15. 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.