Skip Headers

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

Previous | Next
| View PDF

# 4 Installing the RUEI Software

This chapter describes the procedure for installing the Apache Web server and RUEI software. The procedure for upgrading an existing RUEI 4.5.x installation to release 5.0 is also described. The post-installation configuration procedure is described in Chapter 5, "Configuring RUEI".

## 4.1 Obtaining the RUEI Software

The RUEI software is available from the Oracle E-Delivery Web site (`http://edelivery.oracle.com`). Select the following media pack criteria:

- Oracle Enterprise Manager

- Linux x86-64

## 4.2 Installing the Apache Web Server and PHP

This section describes the installation and configuration of the Apache Web server, and the components that use it.

### 4.2.1 PHP Configuration

1. Ensure that the Web server starts automatically after re-boot by issuing the following command:

       /sbin/chkconfig httpd on

2. Edit or create the `/etc/ruei.conf` file to contain the following lines:

       export JAVA_HOME=/u01/app/oracle/product/11.1.0/db_1/jdk/jre
       export INSTANTCLIENT_DIR=/usr/lib/oracle/11.1/client64
       ## Do not change the information below.
       #
       export TNS_ADMIN=/var/opt/ruei
       #
       export PATH=${INSTANTCLIENT_DIR}/bin:${PATH}
       export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${INSTANTCLIENT_DIR}/lib
       export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${JAVA_HOME}/lib/amd64
       export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${JAVA_HOME}/lib/amd64/server

   An example of this file is included in the RUEI distribution pack. Note if the Oracle database has been installed to a different location than that specified in the JAVA_HOME setting, you should specify the required location. Ensure that the file is readable by the `moniforce` user by issuing the following command:

       chmod 644 /etc/ruei.conf

3. Edit the `/etc/sysconfig/httpd` file to include the following line at the bottom of the file:

       source /etc/ruei.conf

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

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

### 4.2.2 Avoiding rsvg Warnings

RUEI uses rsvg for graph generation. In order to avoid warnings about a missing directory, create the empty `.gnome2` directory using the following command:

    mkdir -p /var/www/.gnome2

## 4.3 Unpacking the RUEI Software

Copy the downloaded RUEI zip file to `/root` directory on the server, and unzip it. Use the following commands:

    cd /root
    unzip package_name.zip

The following directories are created which contain the software needed to complete the RUEI installation:

- `/root/RUEI/50`

- `/root/RUEI/ZendOptimizer`

- `/root/RUEI/IC`

- `/root/RUEI/PHP`

## 4.4 Installing the Oracle Database Instant Client

Install the Oracle database Instant Client and SQLplus extension with the following commands as the `root` user:

    cd /root/RUEI/IC
    rpm -Uhv oracle-instantclient11.1-basic-*.rpm
    rpm -Uhv oracle-instantclient11.1-sqlplus-*.rpm

## 4.5 Installing the php-oci8 Module

Install the `php-oci8` module (this is part of the RUEI distribution set) using the following commands:

    cd /root/RUEI/PHP
    rpm -Uhv php-oci8-11gR1-*

## 4.6 Installing the Zend Optimizer

Go to the directory containing the Zend Optimizer code, unpack the tar file, and run the Zend optimizer installer. Read the license agreement. You will not be able to proceed until you have accepted the license terms. Accept all default settings, and allow the installer to restart the Apache Web server. Issue the following commands:

    cd /root/RUEI/ZendOptimizer
    tar zxvf ZendOptimizer-3.3.3-linux-glibc23-x86_64.tar.gz
    cd ZendOptimizer-3.3.3-linux-glibc23-x86_64
    ./install

Note:

If you upgrade your system packages (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. When doing so, ensure the Zend Optimizer installer indicates the location of the `php.ini` file as `/etc/php.ini` and not `/usr/local/Zend/etc/php.ini`.

## 4.7 Installation of the RUEI Software

1. The RUEI file and directory locations are fixed. Therefore, it is necessary to use the exact directory name described below. Create the RUEI application root directory using the following command:

       mkdir -p /opt/ruei

2. Create the `moniforce` group and user. The home directory of `moniforce` should be set to `/var/opt/ruei`, with read permissions for group members.

       /usr/sbin/groupadd moniforce
       /usr/sbin/useradd moniforce -g moniforce -d /var/opt/ruei
       chmod -R 750 /var/opt/ruei
       chown -R moniforce:moniforce /var/opt/ruei

3. Make the `apache` and `moniforce` members of two additional groups using the following commands:

       /usr/sbin/usermod -aG moniforce apache
       /usr/sbin/usermod -aG uucp apache
       /usr/sbin/usermod -aG uucp moniforce

4. Set the ORACLE_HOME environment variable. This is mandatory for preparation of the Oracle database. Issue the following command:

       export ORACLE_HOME=/u01/app/oracle/product/11.1.0/db_1

5. Run the `ruei-prepare-db.sh` script as `root`. This script performs various environment and hardware checks, creates the `ux` database, and is located in the `/root/RUEI/50` directory. Password credentials for connecting to the database are stored in an Oracle wallet. The script prompts you for the RUEI database user password, and the password used to protect the wallet. Once the wallet password is stored in a secure location, the RUEI application can login to the database automatically. The default location of the wallet files are `cwallet.sso` and `ewallet.p12` in the `/var/opt/ruei` directory. Make the script executable and run it using the following commands:

       cd /root/RUEI/50
       chmod +x ruei-prepare-db.sh ruei-check.sh
       ./ruei-prepare-db.sh

   The script prompts you for the intended deployment type. Enter `reporter`, `collector`, or `both`, depending on the planned deployment.

6. Add the following lines to the `/etc/profile` file to make the Oracle database known to RUEI:

       ORACLE_SID=uxexport ORACLE_SID

7. Go to the directory which holds the RUEI software, and install the RUEI RPM packages with the following commands:

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

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

       /sbin/service httpd restart

9. Verify the Oracle database is up and running by changing to the `moniforce` user and obtaining an SQL*Plus prompt with the following commands:

       su - moniforce
       sqlplus /@uxinsight

10. As the `moniforce` user, set the RUEI Administration password to enable logging onto the RUEI interface with the following commands:

        su - moniforce
        set-admin-password

    You are prompted to enter and confirm the password.

    Note:

    When defining the Administrator password, bear the following in mind:

    - The password must have at least eight characters, and contain at least one non-alphanumeric character (such as $, @, &, and !).

    - The initial password must be changed within seven days.

    - The user name and password are case sensitive.

## 4.8 Configuring the Network Interface

Make the monitoring network interface up status permanent (after a reboot) by setting the ONBOOT parameter of the capturing interfaces to yes in the interface configuration files. The network interfaces configuration can be found in `/etc/sysconfig/network-scripts/devices/ifcfg-eth` `X` (where `X` represents the necessary network interface). Alternatively, use the graphical utility system-config-network to set the appropriate interfaces to "activate device when computer starts".

## 4.9 Enabling Multibyte Fonts (Optional, but Recommended)

For PDF generation with multibyte character content, additional fonts need to be enabled. These fonts need to be made available to Java. Use the following command to copy (or move) the RUEI-installed fonts to the appropriate Java directory:

    cp /var/www/ruei/include/bi_publisher/fonts/* \
    /u01/app/oracle/product/11.1.0/db_1/jdk/jre/lib/fonts/

## 4.10 Mail (MTA) Configuration (Optional, Reporter Only)

RUEI assumes a working local MTA for sending PDF reports and E-mail alerts. By default, Enterprise Linux uses the Sendmail MTA. By default, Sendmail will deliver the E-mail directly to the destination MTA. If this behavior is not according to your needs or policies, sending mail via a SmartHost (relay) might be an alternative. To configure a SmartHost in Sendmail, do the following:

1. Find the line which contains the Smart Host setting in `/etc/mail/sendmail.mc`. Modify the SMART_HOST setting to your needs. For example:

       define('SMART_HOST', 'my.example')dnl

2. Generate the new configuration into a new `sendmail.cf` by executing the following command:

       make -C /etc/mail

3. Restart sendmail. For example:

       /etc/init.d/sendmail restart

## 4.11 SNMP (Optional, Reporter Only)

You can download the RUEI MIB definition file through the Reporter interface. This definition file can be added to the SNMP manager. The procedure for downloading the MIB file is described in the Oracle Real User Experience Insight User Guide.

## 4.12 Configuring Automatic Browser Redirection (Optional)

To have the browser automatically redirected to the correct RUEI path, create the file `/var/www/html/index.html` with the following content:

    <head>
                       <meta http-equiv="REFRESH" content="0;URL=/ruei/">
                       </head>

## 4.13 Configuring Reporter Communication (Split-Server Setup Only)

A password-less SSH connection must be setup between the Moniforce user from the Reporter system to each Collector system. Do the following:

1. Logon to the Reporter server as root. Issue the following commands:

       su - moniforcessh-keygen -P ""

   Press Enter to accept the defaults.

2. Logon as `root` on each of the Collector systems. Issue the following commands:

       su - moniforcecd ~/.sshssh root@Reporter cat /var/opt/ruei/.ssh/id_rsa.pub >> authorized_keys

   (you will need to specify the Reporter system root password)

       chmod 600 authorized_keys

3. Check that it is now possible to execute a remote command (as `moniforce` user) on the Reporter system without using a password. For example:

   - Logon as root on the Reporter server.

   - Logon as moniforce user: `su - moniforce`.

   - Execute a remote pwd command: `ssh` Collector `pwd`.

   - Enter yes to the question "Are you sure you want to continue connecting (yes/no)?".

   - The command should return `/var/opt/ruei`.

4. The above steps must be performed for each Collector!

   Note:

   If the connection between the Reporter and the Collector(s) has not been correctly configured, you will receive an authorization error when you try to register the remote Collector.

## 4.14 Verifying Successful Installation of RUEI

On completion of the Initial Setup Wizard (described in Section 5.2, "Performing Initial RUEI Configuration"), you can verify your installation by selecting System, the Status. All system indicators should report OK. Note Status notification will indicate "Unknown" because no system alerts have yet been configured. This is fully described in the Oracle Real User Experience Insight User Guide.

## 4.15 Upgrading From RUEI 4.5.x to 5.0

This section describes the procedure for upgrading an existing RUEI 4.5.x installation to release 5.0. For information on upgrading to RUEI 5.0 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 4.15.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 Guide. In addition, it is strongly recommended you carefully review the information in Section 4.15.1, "Differences Between 4.5.x and 5.0" before performing an upgrade.

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. Otherwise, your system may become unreliable. Ensure you following 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. 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/50
       chmod +x ruei-upgrade-4.5-5.0.sh

2. Stop all processing by issuing the following command:

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

3. RUEI 5.0 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.0.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-*

6. Install the PHP LDAP RPM using the following commands:

       cd /mnt/dvd/Server
       rpm -Uhv php-ldap-11gR1-*

   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. Add the `/etc/ruei.conf` file to contain the following lines:

       export JAVA_HOME=/u01/app/oracle/product/11.1.0/db_1/jdk/jre
       export INSTANTCLIENT_DIR=/usr/lib/oracle/11.1/client64
       ## Do not change the information below.
       #
       export TNS_ADMIN=/var/opt/ruei
       #
       export PATH=${INSTANTCLIENT_DIR}/bin:${PATH}
       export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${INSTANTCLIENT_DIR}/lib
       export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${JAVA_HOME}/lib/amd64
       export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${JAVA_HOME}/lib/amd64/server

   An example of this file is included in the RUEI distribution pack. Note if the Oracle database has been installed to a different location than that specified in the JAVA_HOME setting, you should specify the required location. 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. If you need to upgrade your acceleractor packages, within the `/root` directory, unzip the RUEI 5.0 package, and all required accelerator zip files. Then go to the directory containing the application files, and install the associated RPMs. Use the following commands:

        cd /root
        unzip Vxxxx.zip
        cd /root/RUEI/50
        rpm -Uhv ux-*

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

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

13. 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 /var/www/ruei/include/bi_publisher/fonts/* \
        /u01/app/oracle/product/11.1.0/db_1/jdk/jre/lib/fonts/

14. Upgrade certain administrative information using the following command:

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

15. Login to the Reporter system as `root`, go to the required directory, and re-initialize the database using the following commands:

        cd /root/RUEI/50
        ./ruei-upgrade-4.5-5.0.sh reinitialize

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

17.     ./ruei-upgrade-4.5-5.0.sh convert_rolling_cubes

    This may take several minutes. Any warnings generated by the script can be safely ignored.

18. Re-start RUEI using the following command:

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

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

        /etc/init.d/httpd restart

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

Troubleshooting Upgrade Problems

The upgrade script `ruei-upgrade-4.5-5.0.sh` logs its actions in the file `/tmp/ruei-upgrade-4.5-5.0.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.0. Therefore, it is recommended you create a 5.0 backup after completion of the upgrade procedure.

### 4.15.1 Differences Between 4.5.x and 5.0

This section highlights a number of reporting differences you may notice between versions 4.5.x and 5.0. 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 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 Guide.

### 4.15.2 Rolling back an Upgrade

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

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/50
       chmod +x ./ruei-rollback-5.0-4.5.sh

2. Run the `ruei-rollback-5.0-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.0-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.0-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:

       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/50
        ./ruei-rollback-5.0-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.0-4.5.sh rpm_post_install

13. Re-start RUEI using the following command:

        ./ruei-rollback-5.0-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 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.0-4.5.sh convert_rolling_cubes

Troubleshooting Rollback Problems

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