Implement a web server plug-in


Overview

WAS v8.5.5 works with a web server to route requests for dynamic content, such as servlets, from web applications. The web server plug-in uses an XML configuration file (plugin-cfg.xml) to determine whether a request is for an application server.

(iseries) The web server provided with IBM i, is already installed under product 5761-DG1 for IBM i V6R1 or 5770-DG1 for IBM i V7R1. TheIBM i web server is referred to as the IBM HTTP Server for IBM i. This web server is different from the IBM HTTP Server provided with WebSphere Application Server, which does not run on IBM i.gotcha

To use the IBM HTTP Server provided with the product, see the information about installing IBM HTTP Server. Otherwise, see the installation information provided with the web server.

Make sure the appropriate plug-in file has been installed on the web server and the configureweb_server_name script has been run to create and configure the web server definition for this web server.

(dist) For a distributed platform web server, use the web Server Plug-ins Configuration Tool to install the appropriate plug-in file to the web server. Then, run the configureweb_server_name script created by the tool to create and configure the web server definition in the WebSphere configuration repository.

If we are making a series of simultaneous changes, such as installing numerous applications, you might want the configuration service disabled until after you make the last change. The web server plug-in configuration service is enabled by default. To disable this service, in the console click...

...and then clear the Enable automated web server configuration processing option.

Avoid trouble: If the installation uses a firewall, make sure configured the web server plug-in to use a port that has been opened.

(iseries) The appropriate plug-in file is installed. In addition, an http profile is created...

The http profile can be used to facilitate the creation of web server definitions.

(dist)(zos) The following steps are performed during the plug-in installation process.

  1. (dist) A node is created.

    An unmanaged node is created when the web server is on a different computer from the application server. An unmanaged node is a node that does not have a node agent running on it. Using unmanaged nodes, the product can represent servers that are not application servers within its configuration topology. This representation enables connection information between those servers and application servers to be maintained.

  2. A web server definition is created.

    We can also use either the console or use the ConfigurewebServerDefinition.jacl script to create a web server definition.

  3. An application or modules are mapped to a web server. If an application to use with this web server is already installed, the application is automatically mapped to the web server. If the application is not installed, select this web server during the "Map modules to servers" step of the application installation process.

  4. The master repository is updated and saved.

(dist)(zos) When you configure a plug-in, the configuration file for that plug-in is automatically created. We can change or tune the default settings for the properties in this configuration file. If we change any of the settings, you must regenerate the file before the changes take effect.

(dist)(zos) Generating or regenerating the configuration file might take a while to complete. After it finishes, all objects in the administrative cell use their newest settings, which the web server can access. If the application server is on the same physical workstation as the web server, the regeneration usually takes about 30 to 60 seconds to complete. The regeneration takes longer if the application server and web server are on different workstations.


Update the plug-in configuration file

  1. Use the console to change the settings in the plug-in configuration file.

    When setting up the web server plug-in, decide whether to have the configuration automatically generated in response to a configuration change. When the web server plug-in configuration service is enabled and any of the following conditions occur, the plug-in configuration file is automatically generated:

    • When the web server is created or saved
    • When an application is installed
    • When an application is uninstalled
    • When the virtual host definition is updated

    (dist) When the plug-in configuration file is first generated, it does not include admin_host on the list of virtual hosts. The information about allowing web servers to access the console describes how to add it to the list.gotcha

    We can either use the console, or issue the GenPluginCfg command to regenerate the plugin-cfg.xml file.

    Complete the following steps to regenerate the plugin-cfg.xml file using the console:

    1. Select...

        Servers > Server Types > web Servers > web_server_name > plug-in properties

    2. Select Automatically generate plug-in configuration file, or click one or more of the following topics to manually configure the plugin-cfg.xml file:

      Avoid trouble: 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.gotcha

      See the topic about web server plug-in configuration properties for more information.

      Avoid trouble: Do not manually update the plugin-cfg.xml file. Any manual updates you make for a web server are overridden whenever the plugin-cfg.xml file for that web server is regenerated.gotcha

    3. Click OK.

    4. (iseries) Propagate the plug-in configuration. To propagate the plug-in configuration from the console, click Servers > Server Types > web Servers > web_server_namePropagate plug-in.

      Another method to propagate the plug-in configuration is to run the GenPluginCfg command.

      You do not need to propagate the plug-in configuration if the web server is on the same machine as the associated stand-alone version of the product. If the propagation of the plug-in configuration fails due to an unknown cause, you must manually copy the plugin-cfg.xml file to the location for the remote web server installation.

      Avoid trouble: If we use the FTP function to perform the copy, and the configuration reload fails, check the file authorities on the plugin-cfg.xml file and make sure that users QTMHHTTP, QNOTES and QEJBSVR have RWX authority. If the authorities are not correct, the web server cannot access the new version of the file, which causes the configuration reload to fail. To check the authorities, run the following IBM i command:

        wrklnk 'plug_in_folder_location/plugin-cfg.xml'

      Then select option 9 to view the authorities assigned to the users (QTMHHTTP, QNOTES, and QEJBSVR).gotcha If the authorities are incorrect, issue the following IBM i command to change the file authorities to the appropriate settings:

        CHGAUT USER(QEJBSVR QTMHHTTP QNOTES) OBJ('plug_in_folder_location/plugin-cfg.xml') DTAAUT(*RWX)

      The plug_in_folder_location is the location specified when you transferred the plugin-cfg.xml file.

    5. You might have to stop the application server and then start the application server for the web server to locate the plugin-cfg.xml file.

  2. Tune the web server.

  3. (dist)(zos) Propagate the plug-in configuration. The plug-in configuration file, plugin-cfg.xml, is automatically propagated to the web server if the web server plug-in configuration service is enabled, and one of the following conditions is true:

    • The web server is a local web server, which means that the web server is located on the same workstation as an application server.

    • The web server is a remote IBM HTTP Server Version 7 that has a running IBM HTTP Server administration server.

    If neither of these conditions are true, you must manually copy the plugin-cfg.xml file to the location of the remote web server installation. Copy the plugin-cfg.xml file in <app_server_root>/profiles/<profilename>/config/cells/../../nodes/../servers/<webservername> to the web server host location, which is <PluginInstallRoot>/config/<webservername>/.

    Important: If we use the FTP function to copy the file, and the configuration reload fails, check the file permissions on the plugin-cfg.xml file, and verify they are set to rw-r--r--. If the file permissions are not correct, the web server is not able to access the new version of the file, which causes the configuration reload to fail.

    If the file permissions are incorrect, issue the following command to change the file permissions to the appropriate settings:

      chmod 644 plugin-cfg.xml

    The AIX FTP function does not preserve file attributes. If we need to manually copy the plugin-cfg.xml from an AIX operating system, you might want to use the AIX RCP function instead of the FTP function to copy the file.

    The remote web server installation location is the location specified when creating the node for this web server.

  4. Copy the keystore file to the keystore directory on the web server.

    Avoid trouble: This step is required for the web server to function properly.gotcha

    For detailed instructions on copying the keystore file, read the topic on configuring the web server plug-in for Secure Sockets Layer.


Results

The configuration is complete. To activate the configuration, stop and restart the web server. If we encounter problems restarting the web server, check the http_plugin.log file for information about what portion of the plugin-cfg.xml file contains an error. The log file states the line number on which the error occurred, along with other details that might help you diagnose why the web server did not start. We can use the console to update the plugin-cfg.xml file.

If applications are infrequently installed or uninstalled, which is usually the situation in a production environment, or if we can tolerate the performance impact of generating and distributing the plug-in configuration file each time any of the previously listed actions occur, consider enabling the configuration service.


Subtopics


Related concepts

  • Select a front end for the WAS topology
  • Transport chains


    Related tasks

    Configure the web server plug-in for Secure Sockets Layer

  • Key store settings
  • Configure transport chains
  • Change the HTTP plug-in configuration
  • Tune web servers
  • (iseries) Select a web server topology diagram and roadmap
  • Adding, managing, and removing nodes
  • (iseries) Stopping an application server
  • (iseries) Start an application server
  • (zos) z/OS - Installing IBM HTTP Server

  • GenPluginCfg command