Installing the WebSphere HTTP Plug-in for z/OS

Why and when to perform this task

The WebSphere HTTP Plug-in for z/OS ships as part of the WebSphere Application Server for z/OS product. To use this plug-in, you must have an IBM HTTP Server for z/OS or OS/390 Version 5.3 configured as part of a z/OS system.

After the application server, the HTTP Server and the plug-in are properly configured:

Note: The HTTP Server interprets a blank in a directive specification as a delimiter and a number sign (#) as the beginning of a comment that should be ignored. Therefore, if you need to use a blank or number sign in a directive, you must include a backslash (\) before the blank or number sign to enable the HTTP Server to correctly process the directive.

To Install and configure the WebSphere HTTP Plug-in for z/OS:

Steps for this task

  1. Make sure a Version 5.3 IBM HTTP Server for z/OS and OS/390 is installed on a z/OS or OS/390 system.
    If you want to use Secure-socket layer (SSL), make sure that the HTTP Server is configured for SSL. The SSL connection between the Web server plug-in and the J2EE server uses the SSL session established by the HTTP Server. (See z/OS HTTP Server Planning, Installing, and Using, Version 5.3, SC34-4826, for a description of how to configure the HTTP Server for SSL.)
  2. If the Web Server is not installed on the same LPAR as the Application Server, follow the following steps to download, in binary format, the WebSphere HTTP Plug-in for z/OS and the plugin-cfg.xml file from the LPAR on which the Application Server is running to the LPAR where the HTTP Server is installed.
    The directory into which the plug-in is downloaded must be readable to the MVS ID under which the HTTP Server is executing.
    1. Use FTP or another file transfer mechanism to download, in binary format, the WebSphere HTTP Plug-in for z/OS from your WebSphere Application Server for z/OS system to the HTTP Server's system and into a directory that is readable to the MVS ID under which the HTTP Server is executing.
      The ihs390WAS50Plugin_http.so DLL is located in the Application Server's install_root/bin/ directory

      Note: Whenever service is applied to the WebSphere Application Server for z/OS product, you must FTP a new copy of the WebSphere HTTP Plug-in for z/OS from the install_root/bin directory.

    2. Set the permissions (755 +p) on the plug-in's ihs390WAS50Plugin_http.so file.
      Using an authorized z/OS user ID, issue the following commands from an OMVS command line prompt to turn on the "p" bit in the HFS where the WebSphere HTTP Plug-in for z/OS is now located:
      chmod 777 ihs390WAS50Plugin_http.so 
      extattr +p ihs390WAS50Plugin_http.so
  3. Add ServerInit,, and ServerTerm directives to the httpd.conf configuration file of the HTTP Server to indicate the entry points to the plug-in's initialization and exit routines.
    These routines exist as entry points init_exit, and term_exit, respectively, within the ihs390WAS50Plugin_http.so DLL file.

    Example: The ServerInit directive is split here for printing purposes. In the actual httpd.conf file, enter this directive on a single line.

    ServerInit /http_plugin_dir/bin/
        ihs390WAS50Plugin_http.so:init_exit /http_plugin_conf/
        plugin-cfg.xml
    ServerTerm /http_plugin_dir/ihs390WAS50Plugin_http.so:term_exit

    Specify the full path to where you put the plugin-cfg.xml file for the variable http_plugin_conf.

    The value you specify for the variable http_plugin_dir depends on whether or not the HTTP Server is on the same LPAR as the WebSphere Application Server.

    • If the HTTP Server is on the same LPAR as the WebSphere Application Server, specify the full path of the Application Server's install_root/bin/ directory.

      Note: If v5.0.2 APAR PK02800 or v5.1.0 APAR PK02801 is applied to the WebSphere Application Server for z/OS environment, the value for the http_plugin_dir must be set to WAS_HOME/bin/.

    • If the HTTP Server is not on the same LPAR as the WebSphere Application Server, specify the full path that you designated as the destination of the FTP operation in the previous step.

      Note: Whenever service is applied to the WebSphere Application Server for z/OS product, you must FTP a new copy of the WebSphere HTTP Plugin-in for z/OS from the install_root/bin directory to this directory on your HTTP Server system.

  4. Add the following Service directive for each application that will be using the Web server plug-in.
    This directive indicates the entry point to the plug-in's request routine. The request routine exists as the entry point service_exit within the ihs390WAS50Plugin_http.so Dynamic Link Library (DLL) file.

    Example: The Service directive is split here for printing purposes. In the actual httpd.conf file, enter this directive on a single line.

    Service /webapp_contextroot/*  /http_plugin_dir/
         ihs390WAS50Plugin_http.so:service_exit

    Specify the application's context root for the variable webapp_contextroot.

    The value you specify for the variable http_plugin_dir depends on whether or not the HTTP Server is on the same LPAR as the WebSphere Application Server.

    • If the HTTP Server is on the same LPAR as the WebSphere Application Server, specify the full path of the Application Server's install_root/bin/ directory.

      Note: If v5.0.2 APAR PK02800 or v5.1.0 APAR PK02801 is applied to the WebSphere Application Server for z/OS environment, the value for the http_plugin_dir must be set to WAS_HOME/bin/.

    • If the HTTP Server is not on the same LPAR as the WebSphere Application Server, specify the full path that you designated as the destination of the FTP operation in the previous step.

      Note: Whenever service is applied to the WebSphere Application Server for z/OS product, you must FTP a new copy of the WebSphere HTTP Plugin-in for z/OS from the install_root/bin directory to this directory on your HTTP Server system.

  5. If any of your servlets sets an HTTP response code by any means, such as using methods lastModified() or setStatus(), and the client does not receive the expected response code, add the following directive to the HTTP Server configuration file:
    ServiceSync On
  6. Configure the plug-in.
    Use either use the Update Web Server Plug-in Configuration page in the administrative console, or issue the GenPluginCfg.sh script to create your plugin-cfg.xml file.

    Both methods will create the plug-in configuration file, plugin-cfg.xml, in EBCDIC format, which is the proper format for execution in a z/OS environment.

    To use the Update Web Server Plug-in Configuration page in the administrative console:

    1. Go to the Update Web Server Plug-in page. Click Environment > Update Web Server Plugin in the console navigation tree.
    2. Click OK.
    3. 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.
  7. Using the administrative console, make sure the virtual host is configured with an alias for the port number used by the z/OS V5.3 HTTP Server. Specify the same port on a <VirtualHost Name=> element in the plugin-cfg.xml file.
  8. If you intend to use a supported Web server plug-in, use the administration console to set the TrustedProxy custom property for the transport to true.
    This mandatory setting enables the application server to use the private headers that the Web server plug-in adds to requests.

    You can set the TrustedProxy property to true from either the Web container Custom Properties page or the HTTP Transport Custom Properties page. If you set it on the Web container Custom Properties page, all transports will support private headers.

    Note: If you try to use private headers without setting the TrustedProxy property to true, the request containing the private headers is rejected, and you might receive either a "403 Request Not Permitted," a "HTTP/1.1 404 Not Found," or some other error message that indicates that the request was rejected. After you set the TrustedProxy property to true, the transport trusts all private headers it receives. Therefore, you must ensure that all paths to the HTTP or HTTPS transport are trusted.

  9. Stop the application server and the HTTP Server and start them again.

    The configuration is complete. To activate the configuration, stop and restart both the application server and the HTTP Server. If the WebSphere HTTP Plug-in for z/OS comes up when the HTTP Server starts again, you receive messages similar to the following:

    WebSphere HTTP Plug-in for z/OS Version x.x Service Level x is starting
    WebSphere HTTP Plug-in for z/OS initializing with configuration file :
        fully_qualified_path_to_the_plugin-cfg.xml_file 
    WebSphere HTTP Plug-in for z/OS initialization went OK :-)
    

Related concepts
Private headers
Related tasks
Modifying the default Web container configuration
Configuring Web server plug-ins
Configuring virtual hosts
Regenerating Web server plug-in configurations
Related reference
HTTP transport custom properties
plugin-cfg.xml file



Searchable topic ID:   trun_plugin_390
Last updated: Jun 21, 2007 9:56:50 PM CDT    WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/trun_plugin_390.html

Library | Support | Terms of Use | Feedback