1. Using Oracle WebLogic Server Proxy Plug-Ins
  2. Installing the Oracle WebLogic Server Proxy Plug-In for Apache HTTP Server

2 Installing the Oracle WebLogic Server Proxy Plug-In for Apache HTTP Server

After you download the Oracle WebLogic Server Proxy Plug-in for Apache HTTP Server, you can load it as a module in your Apache HTTP Server installation. To download the proxy plug-in, see Availability of Oracle WebLogic Server Proxy Plug-Ins.

This chapter includes the following topics:

Installation Prerequisites

Before you install the Oracle WebLogic Server Proxy Plug-in for Apache HTTP Server, ensure that you meet the necessary prerequisites.

This section includes the following topics:

Parent topic: Installing the Oracle WebLogic Server Proxy Plug-In for Apache HTTP Server

Obtaining the Proxy Plug-Ins

To obtain the Oracle WebLogic Server Proxy Plug-ins:
  1. Download the Oracle WebLogic Server Proxy Plug-in for Apache HTTP Server, as described in Availability of Oracle WebLogic Server Proxy Plug-Ins.
  2. Extract the proxy plug-ins zip distribution to PLUGINS_HOME. For example, /home/myhome/weblogic-plugins-14.1.1.0.0/. This is the directory to which the proxy plug-in is extracted.

Table 2-1 lists the files included in the distribution.

Table 2-1 Files Included in the Oracle WebLogic Server Proxy Plug-In Zip File for Linux

(Path)/File Name Description

README.txt

The README file for the proxy plug-in.

THIRD_PARTY_LICENSES.txt

The file containing the third-party license related information.

bin/orapki

The orapki tool for configuring Oracle wallets.

bin/export_wallet

The executable file for exporting Oracle wallet to PEM formatted files.

jlib/*.jar

The helper Java libraries for orapki and the export_wallet program.

lib/mod_wl_24.so

The Oracle WebLogic Server Proxy Plug-in for Apache HTTP Server 2.4.

lib/*.so

The helper libraries.

lib/nghttp2/*

The HTTP/2 C library for nghttp2.

Parent topic: Installation Prerequisites

Java Requirements

Install the required version of Java (JDK). Table 2-2 lists the minimum JDK versions required for certain features when using the 14.1.1.0.0 proxy plug-ins for Apache HTTP Server.

Table 2-2 Minimum JDK Requirements

Host on Which JDK Must be Installed Feature that Requires JDK Minimum JDK Version Required Description
Machine on which the Apache HTTP Server is installed. To use for managing Oracle wallet. Oracle JDK 8 JDK is required for using the orapki tool (located at $PLUGINS_HOME/bin) to work with Oracle wallets configured for the web server.

JDK is also required for export_wallet program (located at $PLUGINS_HOME/bin) that exports the content of the Oracle wallets to PEM formatted files on the file system.

Machine on which the back-end Oracle WebLogic Server is deployed. To use TLSv1.3 communication between the web server and the back-end Oracle WebLogic Server. Oracle JDK 8u261-b12 This is the minimum JDK version that includes an implementation of the Transport Layer Security (TLS) 1.3 specification (RFC 8446). Therefore, the back-end Oracle WebLogic Server must use this version of Java to support TLSv1.3 protocol.
To use HTTP/2 protocol over SSL for communication between the web server and the back-end Oracle WebLogic Server. Oracle JDK 8u261-b12 The back-end Oracle WebLogic Server must use this version of Java to support HTTP/2 protocol over SSL.

Parent topic: Installation Prerequisites

Apache HTTP Server Installation

Ensure that you have a supported Apache HTTP Server installation. See Oracle Fusion Middleware Supported System Configurations.

Ensure that you are using Apache Portable Runtime 1.7.0 (apr-1.7.0). Add the path of apr-1.7.0 to the LD_LIBRARY_PATH using the following command: 

export LD_LIBRARY_PATH=<absolute_path_to_the_directory_containing_apr-1.7.0>/lib:${LD_LIBRARY_PATH}

Note:

Oracle WebLogic Server 14.1.1.0.0 proxy plug-ins have been tested with Apache Portable Runtime 1.7.0 (apr-1.7.0). Therefore, it is recommended to use this version of APR at a minimum. It is not known if using earlier versions of APR with proxy plug-ins will result in the correct behavior.

You can download APR from https://apr.apache.org/.

Parent topic: Installation Prerequisites

Oracle WebLogic Server Installation

Ensure that a supported version of Oracle WebLogic Server is configured and running on a target system. This server does not need to be running on the system on which you extracted the proxy plug-in zip distribution.

For the list of supported Oracle WebLogic Server versions, see https://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html.

For information about configuring Oracle WebLogic Server, see Planning the Oracle WebLogic Server Installation in Installing and Configuring Oracle WebLogic Server and Coherence.

Parent topic: Installation Prerequisites

Setting the Environment Variables for Oracle WebLogic Server Proxy Plug-In

Note:

Oracle recommends that you set the environment variables, such as PLUGINS_HOME, JAVA_HOME, and LD_LIBRARY_PATH.
For example:
PLUGINS_HOME=<absolute_path_to_the_directory_where_plugin_zip_is extracted_to>
export PLUGINS_HOME

You can use the variables set at the time of starting the Apache HTTP Server in the httpd.conf file by using the ${VAR_NAME} syntax. For example: 

LoadModule weblogic_module ${PLUGINS_HOME}/lib/mod_wl_24.so

Set the following environment variables:

  • Set PLUGINS_HOME to point to the directory where the proxy plug-ins zip file is extracted to, using the following command:
    export PLUGINS_HOME=<absolute_path_to_the_directory_where_plugin_zip_is extracted_to>

    For example:

    export PLUGINS_HOME=/home/myhome/weblogic-plugins-14.1.1.0.0/
  • Set JAVA_HOME to point to the JDK present on the host where Apache HTTP Server is installed, using the following command:

    Note:

    Relative path is not allowed for JAVA_HOME. 
    export JAVA_HOME=<absolute_path_to_the_JDK8_installation_directory>

    For example:

    export JAVA_HOME=/home/myhome/jdk8

    Note:

    JAVA_HOME is required only when implementing SSL for managing the Oracle wallet.

    For information about the supported JDK versions, see Table 2-2.

  • Ensure that $PLUGINS_HOME/lib appears in the LD_LIBRARY_PATH on UNIX systems. To add $PLUGINS_HOME/lib to the LD_LIBRARY_PATH, use the command: 

    export LD_LIBRARY_PATH=$PLUGINS_HOME/lib:$LD_LIBRARY_PATH
  • Review the Third-Party Software Dependencies to determine if additional steps are needed to satisfy the dependency on the nghttp2 library.

Parent topic: Installation Prerequisites

Installing the Oracle WebLogic Server Proxy Plug-In

The Oracle WebLogic Server Proxy Plug-in for Apache HTTP Server is distributed as a shared object (.so) file. You can obtain the proxy plug-in from the Oracle Web Tier Downloads page or the Software Delivery Cloud.

To install the Oracle WebLogic Server Proxy Plug-in:

  1. Verify that the mod_so.c module is enabled.

    If you installed Apache HTTP Server using the script supplied by Apache, mod_so.c is already enabled. Verify that mod_so.c is enabled by executing the following command:

    UNIX/Linux:
    APACHE_HOME/bin/apachectl -l

    (APACHE_HOME is the directory that contains the Apache HTTP Server installation.)

    This command lists all enabled modules. If mod_so.c is not listed, you must rebuild your Apache HTTP Server, ensuring that the following configuration option is specified: 

    ...
--enable-module=so
...
    The output appears as follows:
    # apachectl -l
Compiled in modules:
...
  mod_so.c
...
  2. Make a copy of the APACHE_HOME/conf/httpd.conf file for backup.
  3. Open the httpd.conf file.
  4. Verify the syntax of the httpd.conf file by running the following command:
    UNIX/Linux:
    > APACHE_HOME/bin/apachectl -t

    If the httpd.conf file contains any errors, the output of this command shows the errors; ensure that you get a clean output before continuing. If there are no errors, the command returns the following: 

    Syntax OK

    Note:

    Ensure that you have resolved all the configuration errors from Steps 1 through 4 before contacting Oracle Support.
  5. The Oracle WebLogic Server Proxy Plug-in modules for Apache 2.4.x are shipped with the 14.1.1.0.0 proxy plug-in distributions. Apache 2.2.x is no longer supported. Therefore, the Oracle WebLogic Server Proxy Plug-in module for Apache 2.2.x is no longer supported. Use the Oracle WebLogic Server Proxy Plug-in module for Apache 2.4.x which continues to be supported.

    Note:

    If you are using Apache 2.2.x version of the web server, migrate to Apache 2.4.x version, and then install the Oracle WebLogic Server Proxy Plug-in module for Apache 2.4.x.

    Install the Oracle WebLogic Server Proxy Plug-in module for Apache 2.4.x by adding the following line:

    LoadModule weblogic_module /home/myhome/weblogic-plugins-14.1.1.0.0/lib/mod_wl_24.so
  6. After installing the Oracle WebLogic Server Proxy Plug-in module, verify the syntax of the httpd.conf file by running the following command:
    UNIX/Linux:
    > APACHE_HOME/bin/apachectl -t

    If the httpd.conf file contains any errors, the output of this command shows the errors. Contact Oracle Support for resolving the errors. If there are no errors, the command returns the following: 

    Syntax OK

Parent topic: Installing the Oracle WebLogic Server Proxy Plug-In for Apache HTTP Server

Next Steps After Installing Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-Ins

After installing the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-in, you should complete the configuration of the proxy plug-in to be able to use its new features.

  1. Review the minimum JDK requirements and install the supported version of JDK. See Installation Prerequisites.
  2. Set the following environment variables:
    • JAVA_HOME
    • PLUGINS_HOME
    • LD_LIBRARY_PATH

    See Installation Prerequisites.

To use the new features of the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins, do the following:

Note:

When the HTTP/2 protocol is configured, the following directives are ignored:

This section includes the following topics:

Parent topic: Installing the Oracle WebLogic Server Proxy Plug-In for Apache HTTP Server

Third-Party Software Dependencies

The Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins depend on the following third-party software:

  • OpenSSL, version 1.1.1
  • nghttp2, version 1.43.0

Libraries from the above third-party software must be available on the system where the Apache Web Server process (that loads the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-in module) runs. These libraries are a prerequisite for the Apache Web Server process to start.

For this reason, Linux Operating systems, which support OpenSSL 1.1.1 by default, are supported with Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins for Apache Web Server. For more information, download the Oracle WebLogic Server (14.1.1.0.0) Certification Matrix from the Oracle Fusion Middleware Supported System Configurations page. When the Apache Web Server process loads the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-in module, the OpenSSL libraries provided by the Operating system are also loaded into the process address space.

In the case of nghttp2, the following options are available for satisfying the dependency:
  • You may be already be using the Open Source Apache Web Server module, mod_http2, in your Apache Web Server installation to support H2 protocol on front-end connections. In this case, you will have a copy of the nghttp2 library (libnghttp2.so). You can use the same library to satisfy the dependency that the Oracle WebLogic Server Proxy Plug-ins have on nghttp2. No further action is required.
  • If you are not using the mod_http2 module in your Apache Web Server installation, the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-in zip file provides a copy of the nghttp2 library under $PLUGINS_HOME/lib/nghttp2. Use this library to satisfy the dependency that Oracle WebLogic Server Proxy Plug-ins have on nghttp2. You can use the library by exporting the LD_LIBRARY_PATH environment variable to the path containing the nghttp2 libraries.
    For example:
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PLUGINS_HOME/lib/nghttp2

Parent topic: Next Steps After Installing Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-Ins

About HTTP Header Case Handling

The Oracle Weblogic Server Proxy Plug-in converts the case of HTTP headers based on the HTTP protocol version configured for the front-end and the back-end connections.

Table 2-3 shows how the case of request and response headers are modified based on the HTTP protocol version configured for the front-end and the back-end connections.

Table 2-3 Case of HTTP Request and Response Headers

HTTP Protocol Version for the Front-End Connection HTTP Protocol Version for the Back-End Connection Case of Request Header Sent to the Back End by the Oracle WebLogic Server Proxy Plug-In Case of Response Header Sent to the Client by the Oracle WebLogic Server Proxy Plug-In
HTTP/2 HTTP/2 Lower Case Lower Case
HTTP/1.1 HTTP/2 Lower Case Camel Case
HTTP/2 HTTP/1.1 Camel Case Lower Case
HTTP/1.1 HTTP/1.1 No Conversion No Conversion

Parent topic: Next Steps After Installing Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-Ins

About Federal Information Processing Standards

Federal Information Processing Standards (FIPS) is not supported in the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins.

If FIPS is configured directly at the Oracle WebLogic Server side, and if a request is made through the Oracle WebLogic Server Proxy Plug-in with a front-end Apache HTTP Server, the request will fail.

Parent topic: Next Steps After Installing Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-Ins

Unsupported Use Cases

The Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins are loaded in an Apache Web Server process that loads open source modules such as mod_ssl.so, mod_http2, and so on, so that they depend on OpenSSL libraries. The Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins also depend on the OpenSSL libraries. The version of OpenSSL that the proxy plug-ins depend on is OpenSSL 1.1.1.

To ensure the current functioning of the Apache Web Server process, Oracle recommends that you ensure that the versions of OpenSSL that different modules within an Apache Web server process use are binary compatible to prevent symbol version conflicts.

If you need to use a version of OpenSSL that is binary incompatible with OpenSSL 1.1.1, you should take the necessary steps to avoid symbol conflicts. For example, dynamically linking with the version of OpenSSL library that supports symbol versioning.

The following use cases are not supported because these lead to an incorrect runtime behavior (process crash) that occurs due to symbol conflicts at runtime:
  • Using the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins in an Apache Web Server process that uses open source Apache modules statically linked with a version of OpenSSL that is binary incompatible with OpenSSL 1.1.1 (such as OpenSSL 1.0.2).
  • Using the Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-ins in an Apache Web Server process that uses the open source Apache modules dynamically linked with a version of OpenSSL that is binary incompatible with OpenSSL 1.1.1 and the OpenSSL library does not support symbol versioning.

Parent topic: Next Steps After Installing Oracle WebLogic Server 14.1.1.0.0 Proxy Plug-Ins

Support and Patching

When you encounter issues with a proxy plug-in, always report the version of the proxy plug-in you are using. You can find this information in the Apache log.

The version information looks like the following snippet:

WebLogic Server Plugin version 14.1.1.0.0 <WLSPLUGINS_XXXX_XXXX_XXXXX.XXXX>

Note:

On the Apache Web Server for Linux, you can also obtain the proxy plug-in version by issuing the following command:
$ strings ${PLUGINS_HOME}/lib/mod_wl_24.so | grep -i wlsplugins

A patch for a proxy plug-in will typically contain one or more shared objects to be replaced. Ensure to backup your original files as you replace them with those in the patch. Validate that the patch has been correctly updated by checking the version string in the logs.

You can obtain the latest updates for security fixes from the Critical Patch Update (CPU) Patch Advisor for Oracle Fusion Middleware (Doc ID 2806740.2).

Parent topic: Installing the Oracle WebLogic Server Proxy Plug-In for Apache HTTP Server