The IBM HTTP Server for WebSphere Application Server plug-in is
provided with the WebSphere Application Server for z/OS Optional Materials.
The plug-in allows 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 .
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
- Use SMP/E to install and load the IBM HTTP
Server for WebSphere Application Server plug-in PTF. By default
the plug-in is placed in the following location: /usr/lpp/zWebSphere_OM/V6R1/HTTP/Plugins/
- 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 the ISPF Customization Dialog or z/OS PMT.
Important: The
following manual steps are involved in order to add a Web server during profile
creation:Because IBM HTTP Server for z/OS is
provided by a PTF for Version 6.1 WebSphere Application Server, in order to
create the Web server plug-in, a manual response file update must be made
to allow the profile creation to correctly process the new Web server type.
If you are using the ISPF Customization Dialog to generate
your customization jobs, perform the following steps after generating the
jobs. If you are using the z/OS Profile Management Tool (PMT), perform the
following steps after uploading your jobs to your target z/OS system.
For a stand-alone application server profile, using
the ISPF Customization Dialog or z/OS PMT:
- Open the BBOWRESP member for editing. This is located in the .DATA dataset.
- Modify the following response file values as specified:
webServerCheck=true
webServerType=IHS
webServerOS=os390
webServerName=name_used_in_defining_the_Webserver_to_Application_Server
webServerHostname=IPname_or_address_of_Webserver
webServerPort=HTTP_port_on_which_Webserver_listens
webServerInstallPath=directory_name_where_Webserver_is_installed
webServerPluginPath=directory_name_where_Webserver_plugins_are_installed
- Submit your customization jobs.
For a cell profile, using the z/OS Profile
Management Tool only:
- Open the BBOWRECN member for editing. This is located in the .DATA dataset.
- Modify the following response file values as specified:
webServerCheck=true
webServerType=IHS
webServerOS=os390
webServerName=name_used_in_defining_the_Webserver_to_Application_Server
webServerHostname=IPname_or_address_of_Webserver
webServerPort=HTTP_port_on_which_Webserver_listens
webServerInstallPath=directory_name_where_Webserver_is_installed
webServerPluginPath=directory_name_where_Webserver_plugins_are_installed
- Submit your customization jobs.
This manual update is required because the validation on the related
z/OS PMT and ISPF Customization dialog panel will not allow you to enter the
combination of
webServerType=IHS and
webServerOS=os390.
- 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.
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:
- 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 Servers > Application Servers > plug-in properties > Request
routing 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, select Application servers > server1 > Web
Container Settings > Web Container Transport Chains > transport_chain > SSL
Inbound Channel (SSL_2) 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 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 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.)