(ZOS) The IBM HTTP Server for WAS plug-in

(ZOS) Install and configure the plug-in for IBM HTTP Server for WAS on z/OS

The IBM HTTP Server for WebSphere Application Server plug-in is part of the web server plug-in component of WAS. The plug-in enables an IBM HTTP Server for WAS to communicate with a WAS. To use this plug-in, we must have an IBM HTTP Server for WAS, which is powered by Apache, and runs on z/OS .

Prior to installing the plug-in, install the IBM HTTP Server for WAS software on your z/OS system, and configure an IBM HTTP Server instance. Refer to the product documentation for installing IBM HTTP Server for WAS on z/OS.

As part of the web server configuration process, we 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, 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 WAS on z/OS.

Tasks
Install web server plug-ins. Use Installation Manager to install the web server plug-ins for WAS for z/OS, and mount the product file system on the target z/OS system. By default, the plug-ins are located in the /usr/lpp/WebSphere/Plugins/V9R0 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/WebSphere/Plugins/V9R0/bin
./install_plugin.sh   
   -pluginInstallLocation /usr/lpp/WebSphere/Plugins/V9R0/
   -pluginRuntimeLocation /etc/websrv1/Plugins
   -wasInstallLocation    /usr/lpp/WebSphere/AppServer/V9R0
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_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 WAS 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 WAS profile use the administrative console, createWebServerDefinition.jacl script, or the wsadmin createWebServer command.

When defining the web server to WAS:

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.
We 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.
Both methods create the plug-in configuration file, plugin-cfg.xml, in ASCII format.
If we 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 > Server Types > Web servers > webserver > Plug-in properties.
Select Automatically generate the 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.
We 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.

We 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 we manually configured the plugin-cfg.xml file, go to the Servers > Server Types > WebSphere application servers > Plug-in properties > Request and response page in the administrative console and make sure that Physically using the port specified in the request is selected for Virtual host matching.
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...
Servers > Server Types > WebSphere application servers > server, and then in the Container Settings section, click Web Container Settings > Web container transport chains > secure_transport_chain > SSL Inbound Channel (SSL_2), and specify this repertoire for that transport chain.
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 v5.3 HTTP Server for z/OS in earlier versions of the product.
If we 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 enabling the use of private headers, the transport chain's SSL inbound channel trusts all private headers it receives. Therefore, ensure that all paths to the transport chain's SSL inbound channel are trusted.

To enable the web server plug-in to use a System Authorization Facility (SAF) keyring instead of a kdb file with a stashfile property, 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.
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/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: 9.0.0
PLUGIN: Bld date: Jun 13 2016, 09:55:09
PLUGIN: Webserver: IHS 390 Webserver: Http Plug-in Build Info: build level 9.0.0.0 (cf031208.05) release WAS90.ZNATV date 06/13/16 09:54:07
PLUGIN: Hostname = ZWASAXXX
PLUGIN: NOFILES = hard: 64000, soft: 64000
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:

WAS 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.)

Related:

Web server definition for z/OS
Private headers
Stopping an application server
Starting an application server
Configure virtual hosts
GenPluginCfg command
Web server plug-in caching properties
Web server plug-in request and response optimization properties
Web server plug-in request routing properties
Web server plug-in configuration service property
Web server plug-in configuration properties