Oracle® Real User Experience Insight Installation Guide Release 5.0 for Linux x86-64 Part Number E12487-08 |
|
|
View PDF |
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".
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
This section describes the installation and configuration of the Apache Web server, and the components that use it.
Ensure that the Web server starts automatically after re-boot by issuing the following command:
/sbin/chkconfig httpd on
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
Edit the /etc/sysconfig/httpd
file to include the following line at the bottom of the file:
source /etc/ruei.conf
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
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
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
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-*
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
.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
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
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
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
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.
Add the following lines to the /etc/profile
file to make the Oracle database known to RUEI:
ORACLE_SID=uxexport ORACLE_SID
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-*
Re-start the Apache Web server using the following command:
/sbin/service httpd restart
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
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.
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".
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/
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:
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
Generate the new configuration into a new sendmail.cf
by executing the following command:
make -C /etc/mail
Restart sendmail. For example:
/etc/init.d/sendmail restart
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.
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>
A password-less SSH connection must be setup between the Moniforce user from the Reporter system to each Collector system. Do the following:
Logon to the Reporter server as root. Issue the following commands:
su - moniforcessh-keygen -P ""
Press Enter to accept the defaults.
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
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
.
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.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.
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:
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
Stop all processing by issuing the following command:
./ruei-upgrade-4.5-5.0.sh stop_ruei
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
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-*
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.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
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
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-*
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.
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 /var/www/ruei/include/bi_publisher/fonts/* \ /u01/app/oracle/product/11.1.0/db_1/jdk/jre/lib/fonts/
Upgrade certain administrative information using the following command:
./ruei-upgrade-4.5-5.0.sh rpm_post_install
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
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.0.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.0.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-*
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.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.
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.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
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.
Stop all RUEI processing by issuing the following command:
./ruei-rollback-5.0-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.0-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:
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/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.
Undo a number of conversion actions by issuing the following command:
./ruei-rollback-5.0-4.5.sh rpm_post_install
Re-start RUEI using the following command:
./ruei-rollback-5.0-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 Guide.
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.