Skip to content

E-WL: Setting Up Apache as a Reverse Proxy Server (RPS) on

WebLogic 10.3.x [ID 1272310.1]
Modified:Jul 20, 2012 Type:HOWTO Status:PUBLISHED Priority:3

In this Document

Goal
Fix
1. Overview of Apache and Examples of how Apache can be Configured in a PeopleSoft
 
Environment.
  2. How to Determine which Apache Version should be Installed for your OS Platform.
  3. How to Download and Install Apache.
  4. How to Install the Apache WebLogic Plug-in
  5. How to Configure Apache with WebLogic Plug-in
  6. Configure WebLogic to use "WebLogic Plugin Enabled" option:
  7. How to Test the Apache Configuration
  8. Troubleshooting Tips
  9. Where to Find more Information.
References

Applies to:
PeopleSoft Enterprise PT PeopleTools - Version 8.50 to 8.52 [Release 8.4]
Information in this document applies to any platform.

Goal
This document provides information for installing, configuring, testing and troubleshooting
when using Apache Reverse Proxy Server with WebLogic 10.3.x, in a PeopleSoft environment.
The instructions also include steps for  installing and configuring the 'Apache HTTP Server
Plug-In'. Note that we recommend you use the Apache HTTP Server Plug-In as it enhances an
Apache installation by enabling WebLogic server to handle load balancing or requests that
require the dynamic functionality of the WebLogic server.

Fix
1. Overview of Apache and Examples of how Apache can be Configured in a
PeopleSoft Environment.

Apache can be used as a Reverse Proxy Server (RPS) to one or more WebLogic PIA's.   When
using Apache, the end user enters a browser URL containing a host name/port# that points to
the RPS, not the WebLogic server.  Below is the sequence of events that occur in a PeopleSoft
environment using an Apache RPS:
  1.  User accesses the PeopleSoft application, from browser, by using a URL containing the
hostname and port# of the RPS. 
       Example:  http://ApacheHost:8080/ps/signon.html
  2. The user request is routed through the Apache RPS and then forwarded to the WebLogic
plug-in.
      The plug-in then evaluates the request and forwards it to the WebLogic PIA.
  3. The WebLogic PIA then processes the request and returns a response via the plug-in to the
Apache RPS.

You can configure Apache RPS to forward requests to either one WebLogic PIA or to multiple
WebLogic PIA's. If using multiple WebLogic PIA's, the PIA's can be in a 'WebLogic Cluster',
or they can be independent PIA's. And they can be on the same machine or multiple machines.

The transmission of requests from Apache RPS to the WebLogic PIA(s) can be completed
using either http or https protocol.

Below are some common reasons for using Apache RPS:

1. When external users needs to access the PeopleSoft application, an Apache RPS is
sometimes installed in the 'DMZ' in order to add a 'layer of protection' between the external
users and the PeopleSoft web server.
2. In cases where there are multiple WebLogic PIA's, Apache RPS may be used to distribute
incoming http requests to the multiple PIA's (instead of using a load balancer)

The diagrams below, show a couple examples of Apache configurations in a PeopleSoft

environment. Note that this is just a couple sample configurations, but Apache can be
configured in many other ways:

2. How to Determine which Apache Version should be Installed for your OS

Platform.

It is important that you install the proper Apache RPS version and that you use a supported
platform. Use the following WebLogic link to determine which Apache version should be
installed for your Operating System:
http://download.oracle.com/docs/cd/E13196_01/platform/suppconfigs/configs103/103_over/ad
d-ons.html
If you configure your PeopleSoft environment with an unsupported Apache version, you may
experience performance issues and/or errors.

3. How to Download and Install Apache.

You can download and install the Apache HTTP server using the following link:
     http://www.apache.org/dist/httpd/

From the above link, you may want to click 'Current Releases' which will direct you to a HTTP
Server Download page which shows best available version.

For Windows, you may wish to choose the 'binary' download file. Note that there are different
files to download depending on whether or not you are installing SSL on Apache.
The following link contains additional detail on installing Apache on Windows:
     http://httpd.apache.org/docs/2.2/platform/windows.html

For Unix, you need to install 'source' download file. Refer to the following link for details on
installing Apache on Unix:
      http://httpd.apache.org/docs/2.2/

4. How to Install the Apache WebLogic Plug-in

There are two versions of Apache plug-in that are supported with WebLogic 10.3.x:
    1) Version 1.0 plug-in
  -OR-
    2) Version 1.1 plug-in

The following document provides details on the differences between Plug-in versions 1.0 and
1.1:
   Document# 1111903.1 WebLogic Server 10gR3 (10.3.0) and 11gR1 (10.3.x) - Web Server
Plug-In Support

You can use either plug-in version in your PeopleSoft environment (version 1.1 must be used if
installing a SHA2 SSL certificate on WebLogic).  Below are instructions for installing each
version. You may find it easier to install version 1.0.

Instructions to Install Plug-In 1.0:

The 1.0 plug-in files are delivered with WebLogic 10.3.x. To get the necessary plug-in for your
Apache RPS, do the following:
   1. Go to the directory where you installed WebLogic (ie WL_HOME)
   2. Then go to subdirectory wlserver_10.3/server/plugin/
   3. Then go to the appropriate subdirectory based on the OS/Platform for your Apache RPS
installation.
   4. You will see several plug-in files. For Apache 2.2.x, you need to use one of the following
plug-ins:
        a. If using http protocol when proxying requests to WebLogic: Use file mod_wl_22.so
        b. If using https protocol when proxying requests to WebLogic: Use file
mod_wl128_22.so
    5. After you locate the plug-in file, copy the file to the 'modules' directory in your Apache
install directory. Example:
          Copy mod_wl_22.so to <APACHE_HOME>/modules

Note: Another option, to get the latest plug-in file, for version 1.0, is to download it from 'My
Oracle Support'. This can be done as follows:
   1. First download the file as follows:
       a. Log into My Oracle Support (MOS)
       b. Go to the 'Patches & Updates' tab
       c. In the 'Patch Search' section:
           i.   Enter patch#10051798
           ii.  Click 'Search' button
           iii. The patch will be displayed. Click on the hyperlink and then click 'download' button
to download the plug-in files.
    2. Now, unzip the file you just downloaded and go to the appropriate directory based on your
Apache OS and Apache version you are installing.
    3. Extract the file for your Apache version and OS.
         a. If using http protocol when proxying requests to WebLogic: Extract file mod_wl_22.so
         b. If using https protocol when proxying requests to WebLogic: Extract file
mod_wl128_22.so
    4. Copy the file to <APACHE_HOME>/modules

Instructions to Install Plug-In 1.1:

   1. Download the file as follows:
        a. Log into My Oracle Support (MOS)
        b. Go to the 'Patches & Updates' tab
        c. In the 'Patch Search' section:
            i.   Enter patch#10051826
            ii.  Click 'Search' button
            iii. The patch will be displayed. Click on the hyperlink and then click 'download' button
to download the plug-in files.
   2. Make a new directory, in your APACHE_HOME directory, for the plug-in files. Example,
directory 'weblogic-plugins-1.1'
   3. Unzip the downloaded file, then find the file for your Apache version and OS. For
example, if using 64 bit Apache 2.2 on a Linux box, you will need file WLSPlugin1.1-
64bitapache2.2-linux64-x86_64.zip.
      Extract the file to <APACHE_HOME>/weblogic-plugins-1.1
5. How to Configure Apache with WebLogic Plug-in

The primary configuration file, for Apache, is the 'httpd.conf' file which is located in your
Apache install directory:APACHE_HOME\conf\httpd.conf

Make the following changes to the 'httpd.conf' file:

1. First, add a line to load the WebLogic plug-in file. There is a section, in httpd.conf, where all
the modules are loaded. You can add a line to the end of this section, for the WebLogic plug-in
module. Note that the name of plug-in file will differ depending on what plug-in version you
are using (as outlined in the previous step). So add the line as follows:
     -If using Plug-In version 1.1, add line:
       LoadModule weblogic_module weblogic-plug-ins-1.1\mod_wl.so
    -If using Plug-In version 1.0 and configuring Apache plug-in to use SSL, add line:
       LoadModule weblogic_module modules\mod_wl128_22.so
    -If using Plug-In version 1.0 and NOT configuring Apache plug-in to use SSL, add line:
       LoadModule weblogic_module modules\mod_wl_22.so

2. Next, add an 'IfModule mod_weblogic.c' section to the end of the httpd.conf file (where the
other 'IfModule' sections are). This section will contain information on how to forward
incoming requests to the WebLogic server.

The following link contains information on all parameters that can be used with the Apache
plug-in for WebLogic:
    
http://download.oracle.com/docs/cd/E12840_01/wls/docs103/plugins/plugin_params.html#wp1
143055

The remainder of this section contains several sample Apache Configurations and the
corresponding values to use in the 'mod_weblogic.c' section (in httpd.conf). You might want to
first start out with a simple configuration (Example 1) and get that working before moving on
to a more complex configuration

EXAMPLE 1: Apache configuration using one PIA (and no SSL)

In this example, Apache is proxying all requests to just one WebLogic PIA located on on web
server box "wlmachine" listening on port 8000:

<IfModule mod_weblogic.c>
   WebLogicHost wlmachine
   WebLogicPort 8000
   MatchExpression /
</IfModule>
EXAMPLE 2: Apache configuration using two PIA's (and no SSL)
In this example, Apache is proxying requests to multiple WebLogic PIA's: Requests are being
forwarded to PIA's listening on ports 8000 and 8001 on web server box "wlmachine".

Note that if you are forwarding requests to multiple PIA's, you must specify the cookie name in
the Apache httpd.conf file, as in the example below. The same cookie name value must be
specified in Apache configuration file (httpd.conf) and WebLogic configuration file
(PS_HOME\webserv\<DOMAIN_NAME>\applications\peoplesoft\PORTAL.war\WEB-
INF\weblogic.xml) for each PIA that Apache is sending requests to:

<IfModule mod_weblogic.c>
   WebLogicCluster wlmachine:8001,wlmachine:8000
   MatchExpression /
   WLCookieName PORTAL-PSJSESSIONID
</IfModule>

EXAMPLE 3: Apache configuration with debug logging enabled

To collect more detail on Apache activity, you can turn on debug logging, using parameters
'Debug ON' and 'DebugConfigInfo On' as in the example below. In this example, the debug
information, for the plug-in, is logged to file c:/tmp/wls_plugin.log:

<IfModule mod_weblogic.c>
   WebLogicCluster wlmachine1:8000,wlmachine2:8000
   MatchExpression /
   WLCookieName PORTAL-PSJSESSIONID
   Debug ON
   DebugConfigInfo On
   WLLogFile c:/tmp/wls_plugin.log
</IfModule>

EXAMPLE 4: Apache configuration using two SSL-enabled PIA's

If Apache is proxying requests to an SSL-enabled PIA, then you must also use parameter
"SecureProxy ON" and you need to specify the location of the trusted root CA, that
Apache needs to complete the SSL handshake with the WebLogic PIA. The parameters
that you use, are different, based on whether you are using plug-in 1.0 or plug-in 1.1.
Below are the steps for configuring the plug-in to communicate to the WebLogic PIA via
https protocol:

1. First, you will need to get the root certificate for the server certificate that the
WebLogic PIA is using (this step applies for both Plug-in versions 1.0 and 1.1). If you do
not have the root certificate for the WebLogic PIA, refer to the following document for
instructions on how to obtain the root certificate:
    Document# 646024.1: E-WS: How to extract the root CA from a server certificate?

At the end of this step, you should have the root certificate in a file. The contents of the
root file, will look something like this:

-----BEGIN CERTIFICATE-----
MIIEJjCCA4+gAwIBAgIQMFbEDgfLmZFFDDT15K+BYDANBgkqhkiG9w0BAQUFADCB
vjD68zPGvIgVDGwnY/uJx2sZi6hLeK5N+Zv5X2nKr1FlLim6fg/mpexm6xY3VIsyza
Gm72Yp2GEbnbCQ==
-----END CERTIFICATE----

Note: If your certificate uses both a root and intermediate certificate, then the above file
should contain both: first the intermediate certificate followed by the root certificate.

2. Next, you will need to change the httpd.conf configuration.

For Plug-In 1.0:

------------------
a. Place the root certificate file (from the step 1 above) in a directory within
APACHE_HOME. In this example, the root file is called "root.cer" and located in
<APACHE_HOME>/conf/Certs/
b. Now, add parameter 'SecureProxy ON' to the WebLogic section in httpd.conf. Also,
add parameter 'TrustedCAFile and specify the location of the root certificate. Also, the
WebLogic ports that you specify, will need to access https ports. Example:

<IfModule mod_weblogic.c>
   SecureProxy ON
   TrustedCAFile "C:/Program Files/Apache Software
Foundation/Apache2.2/conf/Certs/root.cer"
   WebLogicCluster wlmachine1:443,wlmachine2:443
   MatchExpression /
   WLCookieName PORTAL-PSJSESSIONID
   Debug ON
   DebugConfigInfo On
   WLLogFile c:/tmp/wls_plugin.log
</IfModule>

For Plug-In 1.1:

-----------------
Place the root certificate file (from step 1 above) in an "Oracle Wallet". Below are the
instructions for creating the Oracle Wallet:
   1. Go to <APACHE_HOME>/weblogic-plugins-1.1/bin
   2. Set the path point to a JDK6. Example
       PATH = d:\WLS1033\jdk160_18\jre\bin;%PATH%
   3. Set the CLASSPATH to reference the jar file in <APACHE_HOME>/weblogic-plugins-
1.1/jlib   /oraclepki.jar. Example
      SET CLASSPATH=C:\Program Files\Apache Software Foundation\Apache2.2\weblogic-
plugins-1.1\jlib\oraclepki.jar
   4. Run the following command to create a wallet:
       java oracle.security.pki.textui.OraclePKITextUI wallet create -wallet my-wallet
-auto_login_only
   5. Now add your root certificate file, to the wallet. Example:
       java oracle.security.pki.textui.OraclePKITextUI wallet add -wallet my-wallet -trusted_cert
-cert "C:\Program Files\Apache Software Foundation\Apache2.2\conf\Certs\root.cer"
-auto_login_only
   6. Now, add parameter 'SecureProxy ON' to the WebLogic section in httpd.conf. Also, add
parameter 'WLSSLWallet' and specify the path location of the Oracle Wallet containing the
root certificate. Also, the WebLogic ports that you specify, will need to access https ports.
Example:

<IfModule mod_weblogic.c>
   SecureProxy ON
   WLSSLWallet="C:\Program Files\Apache Software
Foundation\Apache2.2\weblogic-plugins-1.1\bin\my-wallet\"
   WebLogicCluster wlmachine1:443,wlmachine2:443
   MatchExpression /
   WLCookieName PORTAL-PSJSESSIONID
   Debug ON
   DebugConfigInfo On
   WLLogFile c:/tmp/wls_plugin.log
</IfModule>

   7. When starting Apache, you'll need to make certain that <APACHE_HOME>\weblogic-

plugins-1.1 is in included in the PATH. Example:
     PATH = C:\Program Files\Apache Software Foundation\Apache2.2\weblogic-plugins-
1.1\lib;%PATH%
     (other options include copying the 'lib' contents to APACHE_HOME\lib)

6. Configure WebLogic to use "WebLogic Plugin Enabled" option:

When using a web server plug-in, we recommend that you set the 'WebLogic Plugin Enabled'
parameter, as there are a few known issues when not setting this parameter, especially if using
https (see document 1300409.1 for details). This  parameter can be set as follows:
   a. Log into WebLogic console (using url http://machine-name:port#/console/)
   b. Click 'Lock & Edit' button on top left page
   c. From left menu, choose Environment -> Servers
   d. Click the 'PIA' hyperlink on right menu.
   e. Go to tab 'Configuration' and sub-tab 'General'
   f. At bottom of page, click the 'Advanced' hyperlink
   g. Check box next to 'WebLogic Plug-In Enabled
   h. Save change
   i. Click 'Activate Changes' button on top left page
7. How to Test the Apache Configuration

Below are steps to test the Apache configuration:

1. First you, should test direct access to the WebLogic PIA to make certain it is accessible.
When you initially test, you may want to configure your WebLogic PIA to use a web profile
that does NOT have an authentication domain or virtual addressing configured. (just to rule out
any issues with misconfigured Web Profile).
To test direct access to the WebLogic PIA, log into the PeopleSoft application, from a browser,
using WebLogic PIA/Port# in the url. Example:
     http://websvr:8000/ps/signon.html

2. Next you should verify that the Apache proxy is up and running (httpd -k start). If you made
any configuration changes, be sure to shut down Apache and restart it.
You can run "netstat -an" to verify that the Apache server is listening on the port that you
configured for the RPS

3. Now try accessing the PeopleSoft application, via the Apache RPS. Example:
    http://ApacheSvr/ps/signon.html

If you can sign in to the PeopleSoft system, your installation and configuration was successful.
If you run into any problems, refer to the next section: 'Troubleshooting Tips'

8. Troubleshooting Tips

Below are a few things you can do to assist in troubleshooting issues with the Apache RPS:

Check Log Files:

If you are experiencing issues accessing the PeopleSoft application using Apache RPS, you
may want to start by checking the Apache logs for any errors.  You can view the logs as
follows:

1.  First make certain that debug logging in enabled for your plug-in. This can be done by
adding parameters 'Debug ON', 'DebugConfigInfo On'  and 'WLLogFile' to the
'mod_weblogic.c' section. Example:

   <IfModule mod_weblogic.c>
      WebLogicCluster wlmachine1:8000,wlmachine2:8000
      MatchExpression /
      WLCookieName PORTAL-PSJSESSIONID
      Debug ON
      DebugConfigInfo On
      WLLogFile c:/tmp/wls_plugin.log
   </IfModule>

Then, restart the RPS (if any configuration changes made) and attempt to access the PeopleSoft
application via the Apache RPS.  Then check the log file for any error details (in the above
example, the log file is located in /tmp/wls_plugin.log)

2. If there is no log file for the plug-in, then this tells us that Apache is never communicating
with the plug-in. In this case, check the Apache log file (instead of the Apache Plug-In log
file).  By default, Apache logs errors to file "logs/error.log"  (search parameter 'ErrorLog' in file
httpd.conf to confirm the log file you are using).

The log files often contain details as to cause of problem, which may help in resolving the
issue.

Validate Configuration Settings in httpd.conf

Make certain you've properly set all parameters in the "IfModule mod_weblogic.c" section of
httpd.conf

If you are getting messaqe "The requested URL /<SITE_NAME>/signon.html was not found
on this server", then verify you have set "MatchExpression /"

If you are getting message "Failure of server APACHE bridge: No backend server
available....", then verify that parameter "WebLogicCluster" (or "WebLogicHost and
WebLogicPort") is pointing to the correct hostname/port# of the WebLogic PIA. And verify
that the PIA(s) are up and running

Validate Web Profile Configuration

If you are able to get to the PeopleSoft signon page, but get an error or 'page not found' after
signing in, then it is possible that there are some issues with the web profile configuration that
you are using.  The web profile configuration parameters, that could cause these problems, are
incorrect setting of the authentication domain and/or the virtual addressing information.    You
may initially want to re-test without any values in these fields.  But ideally, these fields should
be set as follows:

-The "authentication domain" should match to the domain specified in the browser url that user
is using to access the PeopleSoft application. So if accessing the PeopleSoft application via
Apache RPS, then the domain should match that of the Apache machine.  For example, if user
access the PeopleSoft application using:
    http://ApacheSvr.mycompany.com/ps/signon.html
Then the 'authentication domain' should be set to '.mycompany.com'  (if you specified an
authentication domain when installing the PIA, then you will also need to check file
"weblogic.xml" and verify it has the proper value for 'CookieDomain'. File "weblogic.xml" is
located in
<PS_HOME>/webserv/<DOMAIN_NAME>/applications/peoplesoft/PORTAL.war/WEB-
INF/)
-The 'default addressing' should be set to the protocol, machine name and port in the browser
url that user is using to access the PeopleSoft application. So when using an Apache RPS, the
user is entering a browser url  that contains the RPS protocol/machine name/prot#. Therefore
you would need to change web profile default addressing to use the RPS values for protocol,
hostname and port#

Check for  session stickiness

When the Apache RPS is configured to forward requests to multiple PIA's, it is very important
that the same cookie name value is specified in the Apache configuration file (httpd.conf) and
in the WebLogic configuration files (weblogic.xml). If the cookie names do not match, you
may see signs of session stickiness when logging into the PIA, such as missing images, out-of-
memory, and being returned to the log on page. You may also see the following types of
messages in the WebLogic Plug-in Apache log (when debug is
enabled):
Wed Nov 5 18:51:22 2008 <45090812259074822> Cookie String missing in the Cookie

Wed Nov 5 18:51:52 2008 <361684812259075125> Trying a pooled connection for

'10.123.58.333/6080/6080'
Wed Nov 5 18:51:52 2008 <361684812259075125> getPooledConn: No more connections in
the pool for Host[10.123.58.333] Port[6080] SecurePort[6080]

Wed Nov 5 18:51:55 2008 <3616848122590751549> Connect returns -1, and error no set to
55, msg 'Operation now in progress'

If you see signs of issues with session stickiness and see the above messages in the WebLogic
Apache Plug-In log, do the following:
1. Make sure that the Apache config file, httpd.conf, is specifying the cookie name using
parameter WLCookieName (note that this parameter used to be called 'CookieName' but the
'CookieName' parameter has been deprecated and can no longer be used.)

2. Verify that the cookie name value, specified in the Apache configuration, matches the cookie
name value specified in the WebLogic configuration file (weblogic.xml) for each PIA that the
RPS is forwarding requests to. The weblogic.xml file is located in
<PS_HOME>\webserver\peoplesoft\applications\peoplesoft\PORTAL.war\web-inf. Below is
an excerpt from the weblogic.xml file showing the cookie setting:

<session-param>
<param-name>CookieName</param-name>
<param-value>PORTAL-PSJSESSIONID</param-value>
</session-param>

3. Lastly, verify you are not using an outdated plugin. Refer to the following document for
details:
    Document# 661519.1 : How to find out if the proxy plugin is outdated?

9. Where to Find more Information.

Below are additional resources with information about using Apache Reverse Proxy Server:

1. There is additional information in the PeopleBooks 'System and Server Administration'

Document (refer to section 'Setting up Reverse Proxy Servers' within chapter 'Working with
Oracle WebLogic'). Below is a link to the Oracle hosted PeopleBooks site:
     http://www.oracle.com/pls/psft/homepage

2. Below is a link from the WebLogic division, on Installing and Configuring the Apache
HTTP Server plug-in:
     http://download.oracle.com/docs/cd/E12840_01/wls/docs103/plugins/apache.html

References
NOTE:1111903.1 - WebLogic Server Web Server Plug-In Support
NOTE:1300409.1 - WebLogic Plug-In Enabled is Required When Using a Web Server Plug-In
with WLS 10.3.4 and Higher
NOTE:646024.1 - E-WS: How to extract the root CA from a server certificate?
NOTE:661519.1 - E-WL: How to Find out if the Proxy Plugin is Outdated for WebLogic