The IBM® HTTP Server
for WebSphere® Application Server plug-in
is part of the web server plug-in component of WebSphere Application Server Version 8. The
plug-in enables an IBM HTTP
Server for WebSphere Application
Server to communicate with a WebSphere Application Server. To use this plug-in,
you must have an IBM HTTP Server
for WebSphere Application
Server, which is powered by Apache, and runs on z/OS®.
Before you begin
Prior to installing the plug-in, install
the IBM HTTP Server for WebSphere Application Server software on your z/OS system, and configure an IBM HTTP Server instance. Refer
to the product documentation for installing IBM HTTP Server for WebSphere Application Server on z/OS.
About this task
As part of the web server configuration process, you will
create an installation directory for the web server instance. In the
examples that follow, a value of /etc/websrv1 is
used for the web server install directory. The recommended location
for plug-in configuration files is the subdirectory Plugins in
the web server install directory. The Plugins directory
will contain a subdirectory conf/WAS_webserver_name,
and the plug-in configuration file plugin-cfg.xml will
usually reside in this directory.
This procedure outlines how
to install and configure the plug-in for IBM HTTP
Server for WebSphere Application Server on z/OS.
Procedure
- Install web server plug-ins. Use IBM Installation Manager to install the web server
plug-ins for WebSphere Application Server for z/OS V8, and mount the product
file system on your target z/OS system.
By default, the plug-ins are located in the /usr/lpp/zWebSphere_Plugins/V8R0 directory.
- Log on to the OMVS shell using the server ID for the Web
server instance. The install_plugin and ConfigureIHSPlugin scripts
must be run under this user ID so that all files are owned by the
same group as the web server instance.
- Create an installation directory for the plug-in. The
directory for the plug-in will contain configuration information to
be used by the plug-in when running under this web server instance.
The recommended location for this directory is subdirectory Plugins in
the web server instance install directory.
To create the runtime
install image, run the command
plugin_smp_location/bin/install_plugin.sh:
./install_plugin.sh
-pluginInstallLocation product_directory_of_plugin_code
-pluginRuntimeLocation install_directory_of_Web_server_plugin
-wasInstallLocation product_directory_of_WebSphere_Application_Server
The
following example is a sample invocation of this command:
cd /usr/lpp/zWebSphere_OM/V6R1/HTTP/Plugins/bin
./install_plugin.sh
-pluginInstallLocation /usr/lpp/zWebSphere_OM/V6R1/HTTP/Plugins
-pluginRuntimeLocation /etc/websrv1/Plugins
-wasInstallLocation /usr/lpp/zWebSphere/V6R1
- Configure the IBM HTTP
Server for z/OS instance to
use the web server plug-in.
Run the command
plugin_runtime_location/bin/ConfigureIHSPlugin.sh to
configure IBM HTTP Server to
use the web server plug-in:
./ConfigureIHSPlugin.sh
-plugin.home install_directory_of_Webserver_plugin
-plugin.config.xml location_of_plugin-cfg.xml_file
-ihs.conf.file location_of_httpd.conf_file
-operating.system ZOS
-WAS.webserver.name Webserver_name_defined_to_WebSphere_Application_Server
-WAS.host.name hostname_or_IP_address_of_WebSphere_Application_Server
The
following example is a sample invocation of this command:
cd /etc/websrv1/Plugins/bin
./ConfigureIHSPlugin.sh
-plugin.home /etc/websrv1/Plugins
-plugin.config.xml /etc/websrv1/Plugins/config/webserver1/plugin-cfg.xml
-ihs.conf.file /etc/websrv1/conf/httpd.conf
-operating.system ZOS
-WAS.webserver.name webserver1
-WAS.host.name appsrv1.mycorp.com
- Create a web server definition in WebSphere Application Server for the local
or remote z/OS Web server.
- To add a web server definition during profile creation, use either
the Profile Management Tool or the zpmt command.
- To add a web server to an existing WebSphere Application Server profile use the
administrative console, createWebServerDefinition.jacl script,
or the wsadmin createWebServer command.
When defining the web server to
WebSphere Application Server:
- For the web server name, use the value specified for WAS.webserver.name
- For the web server plug-in install directory, use the value specified
for PluginRuntimeLocation
- Configure the plug-in. Use either the administrative
console or issue the GenPluginCfg command to create your plugin-cfg.xml file.
Avoid trouble: You must delete the
plugin-cfg.xml file
in the
profile_root/config/cells directory
before you complete this task. Otherwise, configuration changes do
not persist to the
plugin-cfg.xml file.
gotcha
Note: Both
methods create the plug-in configuration file,
plugin-cfg.xml,
in ASCII format.
- If you need to edit this file, issue the following command to
convert the file to EBCDIC format:
iconv -f ISO8859-1 -t IBM-1047 plugin-cfg.xml.ASCII > plugin-cfg.xml.EBCDIC
- Edit the file, and then issue the following command to convert
it back to ASCII format:
iconv -f IBM-1047 -t ISO8859-1 plugin-cfg.xml.EBCDIC > plugin-cfg.xml.ASCII
To use the administrative console:
- Select Servers > Web Servers > webserver >
plug-in properties.
- Select Automatically generate plug-in configuration file or
click on one or more of the following topics to manually configure
the plugin-cfg.xml file:
- Caching
- Request and response
- Request routing
- Service
- Click OK.
- You might need to stop the application server and then start the
application server again to enable the web server to locate the plugin-cfg.xml file.
You might need to manually copy the plugin-cfg.xml file
to the correct location in the web server plug-in install directory.
- Make sure the virtual host is configured with an alias
for the port number used by the IBM HTTP
Server for z/OS. If you manually
configured the plugin-cfg.xml file, go to the page
in the administrative console and make sure that Physically using
the port specified in request is selected for Virtual host
matching.
- If you want to enable the web server plug-in to use private
headers, define an SSL configuration repertoire that defines a trust
file. Then in the administrative console, click server_name, and then in the Container
Settings section, click transport_chain,
and specify this repertoire for that transport chain.
Avoid trouble: The trust file provides the same functionality
for the IBM HTTP Server for z/OS, powered by Apache, as the
TrustedProxy custom property provided for the Version 5.3 HTTP Server
for z/OS in earlier versions
of the product.
gotcha
If you try to use private headers without
setting up an SSL configuration repertoire that does not include a
trust file definition, the private headers will be ignored. If the
private headers are ignored, the application server might not locate
the requested application.
After you enable the use of private
headers, the transport chain's SSL inbound channel trusts all private
headers it receives. Therefore, you must ensure that all paths to
the transport chain's SSL inbound channel are trusted.
- If you want to enable the web server plug-in to use a System
Authorization Facility (SAF) keyring instead of a kdb file with a
stashfile property, you must create the following two custom plug-in
properties from the administrative console.
- KeyringLocation, which is set to the directory location of the
SAF keyring
- StashfileLocation, which is set to "" (null)
See the information about web server plug-in configuration
properties for instructions on how to create KeyringLocation and StashfileLocation
from the administrative console in order to use a SAF keyring in
your SSL configuration. See also the information in plugin-cfg.xml
file.
- The configuration is complete. To activate the
configuration, stop and restart both the application server and IBM HTTP Server.
Results
If the IBM HTTP Server
plug-in for z/OS comes up successfully
when IBM HTTP Server starts
again, a message is added to the plug-in log file, /plugin_runtime_dir/log/webserver_name/http_plugin.log.
The message that appears in http_plugin.log is similar to
the following sample output:
PLUGIN: Plugins loaded.
PLUGIN: --------------------System Information-----------------------
PLUGIN: Bld version: 6.1.0
PLUGIN: Bld date: Jul 13 2006, 09:55:09
PLUGIN: Webserver: IBM_HTTP_Server/6.1 Apache/2.0.47 (Unix)
PLUGIN: Hostname = ZWASAXXX
PLUGIN: NOFILES = hard: 3000, soft: 3000
PLUGIN: MAX COREFILE SZ = hard: 4194304, soft: 4194304
PLUGIN: DATA = hard: INFINITE, soft: INFINITE
PLUGIN: --------------------------------------------------------------
What to do next
After the application server, the IBM HTTP Server, and the plug-in are properly
configured:
- WebSphere Application Server for the z/OS platform can use this plug-in
to perform regular plug-in functions.
- Requests can be routed from a browser, through the IBM HTTP Server and plug-in, to an application
server on which the requested application is deployed. A new request
is sent to a randomly selected application server on which the application
is deployed. After a session is established, subsequent requests are
routed to the application server assigned to the original request.
- Use private headers as a mechanism for forwarding proxy information
from the web server plug-in to an application server on a z/OS system. (This information
is not otherwise included with HTTP requests.)