Skip Headers
Oracle® Access Manager Installation Guide
10g (10.1.4.3)

Part Number E12493-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

16 Configuring Apache v1.3-based Web Servers for Oracle Access Manager

This chapter explains how to configure Apache v1.3-based Web servers for Oracle Access Manager. Included are Apache Web server and Oracle HTTP Server.

The following topics are provided:

See Also:

16.1 About Oracle HTTP Server and Oracle Access Manager

Oracle HTTP Server is an Internet Web server extension that Oracle Access Manager uses to identify Web server components (WebPass, Policy Manager, WebGate) that communicate with the Oracle HTTP Server. Both Web Server releases, Oracle HTTP Server 10g R2 (10.1.2) or 10g (10.1.3.1.0), provide independent packages based on Apache v1.3 and Apache v2.0. This extension is reflected in Oracle Access Manager package names. For example:


Apache v2.0 packages are named with OHS2:
Oracle_Access_Manager10_1_4_3_0_Win32_OHS2_WebGate

Apache v1.3 packages are named with OHS:
Oracle_Access_Manager10_1_4_3_0_platform_OHS_WebPass

Oracle Access Manager Web components can be installed on a standalone Oracle HTTP Server on Linux and Windows platforms. Here are some considerations for use with Oracle Application Server:

For complete details about Oracle HTTP Server, see the Oracle HTTP Server Administrator's Guide 10g R2 (10.1.2).

Be sure to familiarize yourself with the following Oracle HTTP Server Web component caveats. See also "Setting Oracle HTTP Server Client Certificates".

16.1.1 Oracle HTTP Server Web Component Caveats on Linux

When using Oracle Access Manager 10.1.4 Web components for Oracle HTTP Server on Linux, be sure to take these caveats into account:

  • Oracle Access Manager uses the Native POSIX Thread Library. LinuxThreads is the default, which requires setting the environment variable LD_ASSUME_KERNEL to 2.4.19. If you are using NPTL, there is no requirement to set the environment variable LD_ASSUME_KERNEL to 2.4.19.

  • When installing Oracle Access Manager 10.1.4 Web components for Apache or Oracle HTTP Server on Linux, you are prompted to install as the same user under which the Web server is running. See the User and Group directive entries in the httpd.conf file. Do not to use username "nobody" and group "nobody." Do not use "root" for anything related to the installation and administration of Oracle Access Manager components.

16.1.2 Oracle HTTP Server Web Component Caveats on Linux and Windows Platforms

When using Oracle Access Manager Web components for Oracle HTTP Server on Windows and Linux platforms, both the Perl module and the PHP module must be commented out in the httpd.conf.

16.2 About Apache v1.3 and Oracle Access Manager

This section explains how Apache's process-based architecture affects various Oracle Access Manager Web components:

16.2.1 Identity Server Accessed through WebPass

For Identity Servers communicating with WebPass for Apache v1.3:

  • Each WebPass instance connects to the Identity Server.

  • Each connection takes up system sources, and each connection has n file descriptors.

  • Set the tuning parameters for Apache so that Apache does not need to start or stop processes too frequently. These settings would be similar with or without Oracle Access Manager.

16.2.2 Policy Manager

With Policy Managers for Apache v1.3:

  • Each Web server process is an instance of the Policy Manager application.

  • Each application maintains its own connections to the directory server. This may not directly affect performance. However, there may be a limit on the directory server side that you may want to consider when other directory server clients are involved.

  • Multiple processes respond to a user's request (multiple HTTP events are triggered to build the frames).

  • Latency of responses cannot be predicted.

  • Fewer processes are better from a UI perspective, but this affects the number of concurrent users.

16.2.3 WebGate

With WebGate for Apache v1.3:

  • There is no shared cache between processes.

  • Each process maintains its own connections to the Access Server.

  • Because each process has its own connection, you should limit the number of WebGate connections. This issue is partially affected by the performance of the systems running the Web servers and Access Servers.

  • Reverse proxy capability may be enabled for Apache Web servers on Solaris and Linux platforms.

16.2.3.1 Example: Apache v1.3 Configuration for UNIX Systems

Apache v1.3 is a process-based Web server. The Apache Web server creates a client process with the filters configured to process each request. As a result, each client process will have a WebGate included in it.

If the Apache Web server is configured to use 250 MaxClients (at peak load), there will be 250 WebGates in execution when all these processes execute. Each WebGate will use the connection configuration specified in the WebGate definition. For example, if the WebGate configuration has 4 connections to an Access Server, each of the client process will create 4 connections to the Access Server configured. So, at peak load, there would be 250 * 4 = 1000 connections to the Access Server.

At the Access Server, each connection corresponds to a Message Thread, which reads client requests from the sockets. At peak load, it would have 1000 threads just to process requests from 1 WebGate with the configuration described here. If there were multiple Apache v1.3 Web servers are configured to go to an Access Server, this number would be the sum of connections from each such Web server. The effect of this would be a large number of threads in the Access Server.

As the number of threads in a process increase, the overhead with respect to CPU utilization, memory utilization increases. Some operating systems would start thrashing if the number of threads is overwhelming, which negatively impacts Access Server performance.

The Apache v1.3 Web server creates and destroys client processes based on the request load. It load balances the requests among the child processes, As a result, each child process will have, at most, 1 request to process for which it requires only one connection to one of the Access Servers.

You could configure 2-3 Access Servers for a WebGate so that the load on the Access Servers from this WebGate is balanced. For example:


If the WebGate1 has 1 connection to Access Server1
1 connection to Access Server 2
1 connection to Access Server 3
Then MaxConnections=3

In this case:


The 1st request from Web server to WebGate1 goes to Access Server1
2nd request from Web server to WebGate1 will go to Access Server2
3rd request from Web server to WebGate1 will go to Access Server3
4th request from Web server to WebGate1 will go to Access Server
and so on.

However, connection 1 to AccessServer2 and AccessServer3 may not be used if, during the life of the child process only, 1 request is sent to WebGate1 from the Web server.

To summarize, in a multi-process Web server such as Apache v1.3, you need only one connection to an Access Server.

In the case of Apache v2, the Web server can be configured to operate in 2 mpm modes: worker_mpm, pre-fork_mpm. Worker_mpm creates threads in the Web server for load balancing requests. In this case ThreadsPerChild and MaxClients are used to determine how many processes are spawned. The maximum number of active child processes is determined by the MaxClients directive divided by the ThreadsPerChild directive. Each process will have a webgate in it. In pre-fork mpm case, it behaves like Apache v1.3, creating 1 child process for each request. For more information, see Chapter 17, "Configuring Web Components for Apache v2-based Web Servers".

16.3 Apache v1.3, Oracle HTTP Server, and Stronghold Requirements

Updating the Web server configuration file is required when installing Oracle Access Manager Web components. Oracle recommends that you choose to automatically update the Web server configuration file when installing Oracle Access Manager Web components.

Oracle Access Manager HTML pages use UTF-8 encoding. Apache-based Web servers allow administrators to specify a default character set for all HTML pages sent out using the AddDefaultCharset directive. This directive overrides any character specified by the application generating the HTML pages. If the AddDefaultCharset directive enables a character set other than UTF-8, Oracle Access Manager HTML pages are garbled.

Oracle recommends that you specify the AddDefaultCharset directive in the Web server configuration file (httpd.conf) as follows to ensure the correct display of Oracle Access Manager HTML pages:

AddDefaultCharset Off

See your Web server documentation for more information about this directive.

In addition, your system must also meet these requirements to implement an Apache v1.3, Oracle HTTP Server, or Stronghold Web server:

16.4 Apache v1.3 and Oracle HTTP Server Support

Recent versions of Apache v1.3 contain important security fixes. It is strongly recommended that you use the most recent release of Apache 1.3. For details, see:

http://apache.org

The base Apache 1.3 Web server does not use SSL for browser connections (responding to https:// requests). An add-on module for SSL support known as mod_ssl is available at:

http://www.modssl.org

The Oracle Access Manager plug-ins for base Apache servers are different from those for Apache with mod_ssl (also referred to as using EAPI) in following:

For more information, see "Preparing for Installation" and "Downloading and Compiling the Base Apache Web Server".

Oracle Access Manager Web components for Apache v1.3 and Oracle HTTP Server may be the only WebGates in your installation or may coexist with other WebGates. For more information, see "Access System Guidelines".

16.5 Compatibility and Platform Support

As described in "Confirming Certification Requirements", you can get the latest certification matrix from Oracle Technology Network at the following URL:

http://www.oracle.com/technology/products/id_mgmt/coreid_acc/pdf/oracle_access_manager_certification_10.1.4_r3_matrix.xls

16.6 Downloading and Compiling the Base Apache Web Server

This discussion applies only to Apache open source v1.3. You can download the latest version of Apache 1.3 from the Apache Web site:

http://apache.org

The SSL plug-in mod_ssl is available from:

http://www.modssl.org

These sites point you to other sites for any additional software needed by Apache or mod_ssl (such as openssl). Instructions for compiling the Apache Web server are included with the software distribution.

In order for the Apache Web server to support Oracle Access Manager plug-ins, the module mod-so must be compiled into the server binary.

To compile Apache or Apache with mod_ssl with mod-so:

  1. Include the configuration option before compiling:

    --enable-module=so
    
  2. Ensure the configuration meets other Oracle Access Manager requirements and compile.

16.6.1 Apache Release Notes

The following URL contains information about the latest version of Apache and a link to pick up binary files for the Apache server:

http://www.apache.org/dist/httpd/Announcement.html

16.6.2 Other Useful Links

The following links provide information on building an Apache release and source code:

16.7 Platform-Specific Compilation Options

Some operating systems require additional options during configuration. Some options listed here may be redundant for some releases of Apache 1.3 but are necessary for other releases.

The following are environment settings for the operating system configuration command for your platform:

Solaris:

CFLAGS=-D_REENTRANT
LDFLAGS=-lpthreads

AIX:

CFLAGS=-D_REENTRANT
LDFLAGS=-lpthreads

HP-UX:

CFLAGS=-D_REENTRANT
LDFLAGS="-lcl -lpthreads"

On HP-UX, you need to use PA-RISC1 compile options (the default).Do not use PA-RISC2 (64-bit) options. When using PA-RISC2, you will receive load errors such as "missing symbol," "bad magic number," or "share object is garbled." Similar errors may also appear under any operating system when loading Apache EAPI (mod_ssl) compiled modules into a plain Apache server.

16.8 Platform Specific Run-Time Settings for AIX

On AIX, you must set the environment variable AIXTHREAD_SCOPE to the value S (uppercase). Otherwise, there may be a segmentation fault when a worker process exits. This, however, does not affect the delivery of content, authentication, or authorization decisions by WebGate.

Also on AIX, you may wish to place the following directive in the httpd.conf file:

AcceptMutex fcntl

This directive is only supported in Apache 1.3.24 and later. It does not affect the delivery of content, authentication, or authorization decisions by WebGate. However, those familiar with the behavior of Apache on other platforms (through the /server-status URL) may prefer to use this setting.

16.9 Installation Order for Oracle Access Manager Web Components

Oracle Access Manager Web components (WebPass, Policy Manager, and WebGate), must be installed in a specific order. For example:


WebPass
Policy Manager
WebGate

For more information, see "About the Installation Task".

16.10 Updating Web Server Configuration for Oracle Access Manager Web Components

During installation of Oracle Access Manager Web components (WebPass, Policy Manager, and WebGate), you can choose to update your Apache Web server configuration file (httpd.conf) manually or automatically. Oracle recommends that you update your Web server configuration file automatically. However, if you choose to update httpd.conf manually, instructions are provided.

When installing Oracle Access Manager Web components you are prompted for the location of the Web server configuration file. For Apache, enter the full path to httpd.conf. For example, the httpd.conf file may be found in the Apache_install_dir/conf directory.

If you later need to re-update the httpd.conf file (after Oracle Access Manager Web component installation and the initial Web server configuration update, refer to the config.htm file in component_install_dir/oblix/apps/common/docs/config.htm, or use the ManageHttpConf program located in component_install_dir/oblix/tools/setup/InstallTools/ManageHttpConf. Running ManageHttpConf without any options will print instructions on its use.

16.11 Tuning Apache 1.3 for Oracle Access Manager Web Components

Apache 1.3 uses a process model for serving multiple http requests at once. This is different from the single process (thread) model employed by other Web servers, which manage several requests simultaneously in one process. Each subordinate Apache worker-process responds to an incoming http request independently of every other worker-process.

Several parameters in the Apache server configuration file (httpd.conf) affect how an Apache server decides to create or destroy worker processes. The following affect the performance of the server:

Appropriate values for the preceding parameters depend on the expected load and the performance class of the systems involved, including the Access Server and LDAP server.

Apache servers on very high performance systems with high expected loads may be recompiled with a larger limit on the number of worker processes. These systems may see a greater performance impact on the StartServers and MinSpareServers parameters for dealing with sudden load spikes.

You may need to adjust operating system limits for the Access Server for proper operation. In particular, the maximum number of file descriptors available for any one Access Server may need to be increased beyond the default value. Configuring more than one connection between each Apache-based WebGate and an Access Server may quickly exceed this limit.

16.11.1 Policy Manager Tuning Factors

Policy Manager performance may be impacted by both Apache and Policy Manager configuration parameters. The following factors should be considered when tuning the Policy Manager for Apache:

  • The idle child processes ensure that a new incoming request is serviced immediately. The more spare child processes, the faster the ramp up.

  • Each child process opens separate connections to the directory server. The more child processes you have, the more directory server connections you have.

Assuming that each user is using one browser, there are four to five simultaneous requests to the Web server for images and js and HTML from the browser. Assuming that there are four simultaneous users, the total number of simultaneous requests to the Web server is 4 * 5 = 20.

Given these factors, Oracle recommends the following to maintain a balance between how fast a new user is serviced and the number of connections to the directory server:

  • MaxClients = 25

  • MinSpareServers = 4

  • MaxSpareServers = 5

Note:

The Policy Manager does not open connections on Web Server startup. Instead, the Policy Manager creates connections on the first request.

To help compensate for any delay when the Policy Manager creates connections, the Policy Manager may be configured such that all directory server connections for all directory server profiles are set to 1. In this case, the Apache configuration may be as follows:

  • MinSpareServers = 1

  • MaxSpareServers = 2

  • MaxServers = 2

In the preceding case, the Policy Manager responds in a reasonable time with some delay on the initial request.

16.12 Setting Oracle HTTP Server Client Certificates

When using the cert_decode and credential_mapping plug-ins, you must ensure that the Access System Client Certificate authentication scheme works properly with SSL-enabled Oracle HTTP Server by adding +EarlierEnvVars and +ExportCertData to the existing SSL options in the Oracle HTTP Server Web server configuration file. For example:

credential_mapping:

obMappingBase="o=company,c=us",obMappingFilter=
     "(&(objectclass=InetOrgPerson)(mail=%certSubject.E%))"

ssl.conf must include:

SSLOptions +StdEnvVars +ExportCertData +EarlierEnvVars

To add ssl options

  1. Locate and open the Oracle HTTP Server Web server configuration file with a text editor. For example:

    $ORACLE_HOME/Apache/Apache/conf/ssl.conf

  2. In the ssl.conf file, add the following information to existing SSL options. For example:

    SSLOptions +StdEnvVars +ExportCertData +EarlierEnvVars
    
  3. Save the file and restart the Web server.

16.13 Tuning Oracle HTTP Server for Oracle Access Manager Web Components

After installing the Oracle Access Manager Web component for Oracle HTTP Server, you need to complete the following steps.

As mentioned earlier, before installing Oracle Access Manager Web components for Oracle HTTP Server, in the httpd.conf file change user and group to match the user that is installing the component.

Note:

Oracle Access Manager for Linux uses the Native POSIX Thread Library only. As a result, there is no requirement to set the environment variable LD_ASSUME_KERNEL to 2.4.19.

To tune Oracle HTTP Server for Oracle Access Manager Web components

  1. Shut down opmn, as you usually do.

  2. Locate and open the opmn.xml file for editing. For example:

    $oracle_home/opmn/bin/opmn.xml

  3. In the opmn.xml file, adjust items as follows:

    <ias-component id="HTTP_Server">
    <process-type id="HTTP_Server" module-id="OHS2">
             <environment>
                    <variable id="TMP" value="/tmp"/>
             </environment>
              <module-data>
                <category id="start-parameters">
                  <data id="start-mode" value="ssl-disabled"/>
                </category>
              </module-data>
              <process-set id="HTTP_Server" numprocs="1"/>
            </process-type>
          </ias-component>
    
  4. Refresh the OPMN configuration by executing the following script:

    #oracle_home/opmn/bin/opmnctl reload
    
  5. In httpd.conf file on the Policy Manager, comment-out the following lines:

    #LoadModule perl_module modules/mod_perl.so
    #LoadModule php4_module modules/mod_php4.so
    
  6. Start the Oracle HTTP Server Web server, as described in "Starting and Stopping Oracle HTTP Server Web Servers".

16.14 Starting and Stopping the Web Server

The following discussions provide information specific to running the Apache server on UNIX and Windows:

16.14.1 Starting and Stopping Oracle HTTP Server Web Servers

Starting and stopping an Oracle HTTP Server Web server is the same procedure for both v1.3 and v2, on all platforms.

To start the Oracle HTTP Server Web server

  1. Locate and change to the following directory:

    $ORACLE_HOME\opmn\bin\

  2. From the command line, enter the following command:

    opmnctl/startproc process-type=HTTP_Server
    

To stop the Oracle HTTP Server Web server

  1. Locate and change to the following directory:

    $ORACLE_HOME\opmn\bin\

  2. From the command line, enter the following command:

    opmnctl/stopproc process-type=HTTP_Server
    

16.14.2 Starting and Stopping Apache on UNIX

Typically, you perform a single step to start or stop the Apache Web server, as discussed in the following procedures:

16.14.2.1 Stopping Apache Web Server on UNIX

To stop your Apache Web server on UNIX:

  1. Locate the Apache_install_dir/bin directory.

  2. From the command line, use the apachectl stop command to stop the server:

    ./apachectl stop
    

16.14.2.2 Starting and stopping the Apache Web Server on UNIX

To start and stop the Apache Web server on UNIX:

  1. Locate the Apache_install_dir/bin directory.

  2. From the command line, use the apachectl command, as follows, to stop and restart the server:

    ./apachectl start
    

16.14.2.3 Starting the Server in SSL Mode

To start the server in SSL mode:

  1. Locate the Apache_install_dir/bin directory.

  2. From the command line, use the apachectl startssl command to start the server in SSL mode:

    ./apachectl startssl
    

16.14.3 Starting and Stopping Apache on Windows

The manner in which you start the apache Web server depends on the manner in which it is running: as a Windows service or as an application. See the procedures that follow.

To stop the Web server running as an application

  1. in the Windows command line, hold down the Control key and then type the letter c.

To stop the Web server running as a Windows service

  1. In the Windows Service window, locate the Web server service name.

  2. Click the Stop icon.

To start the Web server running as a Windows service

  1. Locate the Apache_install_dir/bin directory.

  2. Enter the following command on the command line:

    apache.exe –k start
    

To start the Web server running as an application

  1. In the Windows Service window, locate the Web server service name.

  2. Click the Start icon.

16.15 Removing Web Server Configuration Changes After Uninstall

Web server configuration changes that occur during installation must be manually removed after uninstalling the Oracle Access Manager component (WebPass, Policy Manager, WebGate). This type of information must be removed manually.

Further, you must remove any changes that you manually made to your Web server configuration file for the Oracle Access Manager component (WebPass, Policy Manager, WebGate) should be removed. For more information about what is added for each component, look elsewhere in this chapter.

16.16 Troubleshooting

For more information, see Appendix E, "Troubleshooting Installation Issues".