Previous | Home | Next


Configure web servers

Web server overview

Web servers work as a front end for WAS appservers, providing...

Load Balancing Using plug-in settings, the web server routes requests to different backend appservers. Plug-ins contain information about appservers, clusters, applications, session affinity, and the weight of JVM. Directory location of plugin files is referenced at the bottom of the web server configuration file, httpd.conf.
Security Enable or disable forwarding of a requests, based on security settings, such as SSL certificates. Protect appservers from untrusted network traffic using filtering and forwarding mechanisms applied at the web server level.
Performance Control Tuning parameters: threads, time out, child threads.

Plug-in configuration files are generated on the application server, and copied into place on the web server. To manage the generation and propagation of these plug-in configuration files, web servers are defined to the WAS configuration repository, on either managed or unmanaged nodes. For managed nodes, a node agent is installed on the web server system and belongs to a WAS administrative cell. The administrative tools communicate with the web server through the node agent. For unmanaged nodes, if you are using IBM HTTP Server V8.5 is bundled with WAS V8.5, can still be managed using the dmgr console connecting to the IHS admin port, generally 8008. See adminctl.

Supported web servers for WAS V8.5:


Request routing using the plug-in

The web server plug-in uses plugin-cfg.xml to determine whether a request is for the web server or the application server. When a request reaches the web server, the URL is compared to the URLs managed by the plug-in. If a match is found, plugin-cfg.xml contains the information needed to forward that request to the web container using the web container inbound transport chain.

The plug-in configuration file, plugin-cfg.xml, is generated using the WebSphere administrative tools. Each time you make a change to the WAS configuration that affects how requests are routed from a web server to the application server, regenerate and propagate plugin-cfg.xml to the web server. We can propagate the file manually or configure the propagation to be done automatically.


Web server and plug-in management

The setup of the web server and web server plug-in environment is defined in a web server definition. The web server definition includes information about the location of the web server, its configuration files, and plug-in configuration. Each web server is association with a node, either managed or unmanaged. The web server definition is configured as part of the plug-in installation process. The web server definition is also used during application deployment. Web modules can be mapped to a web server, ensuring the proper routing information is generated for plugin-cfg.xml.

Web server definitions are located under...


Contrasting managed and unmanaged

In a distributed server environment, we can define multiple web servers. These web servers can be defined on managed or unmanaged nodes depending on the environment on which we are running the web server. This section covers the differences between managed and unmanaged nodes.

WAS supports basic administrative functions for all supported web servers. For example, the generation of a plug-in configuration can be performed for all web servers. If the web server is defined on a managed node, automatic propagation of the plug-in configuration can be performed using node synchronization. If the web server is defined on an unmanaged node, automatic propagation of a plug-in configuration is only supported for IBM HTTP Servers.

WAS supports some additional dmgr console tasks for IBM HTTP Servers on managed and unmanaged nodes. For example, we can start IBM HTTP Servers, stop them, terminate them, display their log files, and edit their configuration files.


Unmanaged nodes

An unmanaged node does not have a node agent to manage its servers. In a stand-alone server environment, we can define one web server and it, by necessity, resides on an unmanaged node. In a distributed server environment, web servers defined to an unmanaged node are typically remote web servers. The web server is usually found in the demilitarized zone (DMZ) outside the firewall. The DMZ is a safe zone between firewalls typically located between a client and a back-end server.

In this configuration, plugin-cfg.xml is generated on the deployment manager. The plug-in configuration file must be manually propagated to the web server on the unmanaged node. To start or stop this web server, use the specific web server administrative tools.

The IBM HTTP Server is a special case. If the web server is IHS, we can configure the server on an unmanaged node and still be able to administer the web server using the WebSphere administrative tools. This unmanaged node does not need a node agent on the web server machine. The IHS administration process provides administrative functions for IHS within WebSphere.

IHS web server configured on an unmanaged node. In this configuration, plugin-cfg.xml is generated on the deployment manager. Because the web server is IHS, we can automatically propagate plugin-cfg.xml to the remote server, make configuration changes to the web server configuration file, and use the dmgr console to start and stop the web server.


IBM HTTP Server on an unmanaged node

If the web server is defined to an unmanaged node, complete these steps:

  1. Check the status of the web server.

  2. Generate a plug-in configuration file for that web server.

    If the web server is an IBM HTTP Server and the IBM HTTP Server Administration server is installed and properly configured, we can also:

    1. Display the IBM HTTP Server Error log (error.log) and Access log (access.log) files.

    2. Start and stop the server.

    3. Display and edit the IBM HTTP Server configuration file (httpd.conf).

    4. Propagate plugin-cfg.xml after it is generated.

    We cannot propagate an updated plug-in configuration file to a non-IBM HTTP Server web server defined to an unmanaged node. You must install an updated plug-in configuration file manually to a web server defined to an unmanaged node.


Managed nodes

A managed node has a node agent for managing web servers. We can use the WebSphere administrative tools to communicate with web servers on a managed node. A web server configured on a managed node. In this configuration, plugin-cfg.xml is generated on the deployment manager. The plug-in configuration file is automatically propagated to the web server on the managed node. To start or stop this web server, we can use the dmgr console.

If the web server is defined to a managed node:

  1. Check the status of the web server.

  2. Generate a plug-in configuration file for that web server.

  3. Propagate plugin-cfg.xml after it is generated.

    If the web server is an IBM HTTP Server and the IBM HTTP Server Administration server is installed and properly configured, we can also:

    1. Display the IBM HTTP Server Error log (error.log) and Access log (access.log) files.

    2. Start and stop the server.

    3. Display and edit the IBM HTTP Server configuration file (httpd.conf).


How nodes and servers are defined

During the installation of the plug-in, the Plug-ins installation wizard creates a web server configuration script named configureWeb_server_name. This configuration script is used to create the web server definition and, if necessary, the node definition in the configuration of the application server.

If a web server definition already exists for a stand-alone application server, running the script does not add a new web server definition. Each stand-alone application server can have only one web server definition. A managed node, conversely, can have multiple web server definitions. The script creates a new web server definition unless the web server name is the same.

The Plug-ins installation wizard stores the script in the PLUGIN_HOME/bin directory on the web server machine. If the plug-in is installed locally (on the same machine as the application server), the configuration script is run automatically.

For remote installations, copy the script from the web server machine to the WAS_HOME/bin directory on the application server machine for execution. The script runs against the default profile. If one machine is running under Linux or UNIX and the other machine is running under Windows, use the script created in the directory...

Always open a new command window in which to execute the configureWeb_server_name script. There is a potential conflict between a shell environment variable, the WAS_USER_SCRIPT variable, and the real default profile. The script always works against the default profile. However, if the WAS_USER_SCRIPT environment variable is set, a conflict arises as the script attempts to work on the profile identified by the variable.

If create a web server definition for a distributed server environment, federate your stand-alone application servers to the deployment manager first. Any web server definitions created for a stand-alone application server are lost when they are federated into a cell.

Using administrative tools: In a distributed server environment, the dmgr console can also be used to define the nodes and web servers.


Installations

We can install a web server and web server plug-in using the Installation Manager. We can perform the installation using the GUI, command line, console mode, or silently. To install the IBM HTTP Server and web server plug-in:

  1. Install IBM Installation Manager.

  2. Launch the Installation Manager GUI.

  3. Configure the Installation Manager repository to point to the Supplements package.

  4. Click the Install wizard to begin the installation.

  5. Select the following packages for installation:

    • IBM HTTP Server for WAS
    • Web Server Plug-ins for IBM WAS

  6. Read and accept the license agreement.

  7. Select the installation directory for each package. We can keep the default paths or update them to suit the environment.

  8. On the Features window, verify the selected packages.

  9. Configure a port number for the IBM HTTP Server to communicate. Keep the default port 80 or modify to a port number not in use.

  10. Review the settings on the Summary window, and click Install.

  11. When the installation is complete, review the summary, and click Finish. It is also a best practice to view the log file to verify the installation was successful.

After installation of the web server and web server plug-in, configure the web server plug-in. To configure the plug-in, the stand-alone WebSphere Customization Toolbox offering must be installed.


Web server configuration using the WebSphere Customization Toolbox

After installing the web server plug-in, configure it.

A new tool in WAS V8.5 is the Web Server Plug-in Configuration Tool in the WebSphere Customization Toolbox (WCT), which is used for configuring web server plug-ins.

The Web Server Plug-in Configuration Tool creates one or more configurations for the web server plug-ins that can direct requests from a web client through the web server and then interact with applications running on an application server.

The Web Server Plug-in Configuration Tool edits the configuration file or files for a web server by creating directives that point to the location of the binary plug-in module and plugin-cfg.xml.

Before configuring the plug-in, determine the topology set up. The options for defining and managing web servers depend on your chosen web server topology and your WAS package. Decisions to make include whether to collocate the web server with other WAS processes and whether to make the web server managed or unmanaged.

The following examples outline the process required to create each sample topology. Note that each example assumes that only the WebSphere processes shown in the diagrams are installed on each system and the profile for the process is the default profile.


Configuration files

When configuring a web server and plug-in, a number of configuration files are created and used:


Stand-alone server environment

In a stand-alone server environment, a web server can be remote to the application server machine or local, but there can only be one defined to WAS. The web server always resides on an unmanaged node.


Remote web server

In this scenario, the application server and the web server are on separate machines. The web server machine can reside in the internal network, or more likely, will reside in the DMZ. Use this configuration for a production environment.

Assume the application server is already installed and configured on Machine A.

  1. Install Installation Manager on Machine B.

  2. Install the web server, web server plug-in, and WebSphere Customization Toolbox on Machine B.

  3. Configure the web server plug-in on Machine B:

    1. Launch the Web Server Plug-ins Configuration Tool.

    2. Configure a remote web server plug-in.

    3. Configure a web server definition. The default is webserver1.

During configuration, the following tasks are completed:

  1. A default temporary plug-in configuration file is created and placed into the location specified.

  2. The web server configuration file is updated with the plug-in configuration, including the location of plugin-cfg.xml.

  3. A script is generated to define the web server to WAS. The script is located in:

      PLUGIN_HOME/bin/configureweb_server_name

  4. At the end of the plug-in configuration, copy the configureweb_server_name script to the <PROFILE_HOME>/bin directory of the application server machine, Machine A. Start the application server, and then execute the script.

  5. When the web server is defined to WAS, plugin-cfg.xml is generated automatically. For the IBM HTTP Server, the new plug-in file is propagated to the web server automatically. For other web server types, propagate the new plug-in configuration file to the web server.

  6. Start the web server, and verify the configuration by accessing an application from a web client.


Local web server

In this scenario, a stand-alone application server exists on machine A. The web server and web server plug-in are also installed on machine A. This topology is suited to a development environment or for internal applications.

Local web server in a stand-alone server environment

Assume the application server is already installed and configured. Complete the following steps:

  1. Install the web server, web server plug-in, and WebSphere Customization Toolbox on Machine A.

  2. Configure the web server plug-in on Machine A:

    1. Launch the Web Server Plug-ins Configuration Tool.

    2. Configure a local web server plug-in.

    3. Configure a web server definition. The default is webserver1.

During configuration, the following tasks are performed:

  1. A default temporary plug-in configuration file is created and placed into the location specified.

  2. The web server configuration file is updated with the plug-in configuration, including the location of plugin-cfg.xml.

  3. A script to define the web server to WAS is generated. The script is located in:

      PLUGIN_HOME/bin/configureweb_server_name

  • At the end of the plug-in configuration, copy the configureweb_server_name script to the <PROFILE_HOME>/bin directory of the application server machine, Machine A. Start the application server and then execute the script.

  • When the web server is defined to WAS, plugin-cfg.xml is generated automatically. Because this is a local installation, we do not have to propagate the new plug-in configuration to the web server. For the IBM HTTP Server, the new plug-in file is propagated to the web server automatically. For other web server types, propagate the new plug-in configuration file to the web server.

  • Start the application server and the web server, and verify the configuration by accessing an application from a web client.


    Web Server plugin configuration in a distributed server environment

    Web servers in a distributed server environment can be local to the application server or remote. The web server can also reside on the deployment manager system. You have the possibility of defining multiple web servers and the web servers can reside on managed or unmanaged nodes. If you are planning to add the application server node into a deployment manager cell but have not done so yet, start the deployment manager and federate the node before configuring the plug-in. We cannot add an application server with a web server definition into the deployment manager cell.


    Remote web server

    The deployment manager and the web server are on separate machines. The web server machine can reside in the internal network, or more likely, it resides in the DMZ. Use this configuration for a production environment.

    Note that this scenario and the process are almost identical to the process outlined for a remote web server in a stand-alone server environment. The primary difference is the script that defines the web server is run against the deployment manager, and you will see an unmanaged node created for the web server node. The node is unmanaged because there is no node agent on the web server system.

    Assume the deployment manager is already installed and configured on Machine A and the application server is already installed and configured on Machine C.

    1. Install Installation Manager on Machine B.

    2. Install the web server, web server plug-in, and WebSphere Customization Toolbox on Machine B.

    3. Configure the web server plug-in on Machine B:

      1. Launch the Web Server Plug-ins Configuration Tool.

      2. Configure a remote web server plug-in.

      3. Configure a web server definition. The default is webserver1.

    During configuration, the following tasks are performed:

    1. A default temporary plug-in configuration file is created and placed into the location specified.

    2. The web server configuration file is updated with the plug-in configuration, including the location of plugin-cfg.xml.

    3. A script is generated to define the web server to WAS. The script is located in:

        PLUGIN_HOME/bin/configureweb_server_name

  • At the end of the plug-in configuration, copy the configureweb_server_name script to the <PROFILE_HOME>/bin directory of the deployment manager machine, Machine A. Start the deployment manager and then execute the script.

  • When the web server is defined to WAS, plugin-cfg.xml is generated automatically. For the IBM HTTP Server, the new plug-in file is propagated to the web server automatically. For other web server types, propagate the new plug-in configuration file to the web server.

  • Start the web server, and verify the configuration by accessing an application from a web client.


    Local to a federated application server

    In this scenario, the web server is installed on a machine that also has a managed node. Note that this scenario functions the same if the deployment manager were installed on Machine B.

    Assume the deployment manager is already installed and configured on Machine A and the application server is already installed and configured on Machine B. Complete the following steps:

    1. Install the web server, web server plug-in, and WebSphere Customization Toolbox on Machine B.

    2. Configure the web server plug-in on Machine B by doing the following:

      1. Launch the Web Server Plug-ins Configuration Tool.

      2. Configure a local web server plug-in.

      3. Configure a web server definition. The default is webserver1.

    During configuration, the following tasks are performed:

      1. A default temporary plug-in configuration file is created and placed into the location specified.

      2. The web server configuration file is updated with the plug-in configuration, including the location of plugin-cfg.xml.

      3. A script is generated to define the web server to WAS. The script is located in:

        PLUGIN_HOME/bin/configureweb_server_name

    1. At the end of the plug-in configuration, copy the configureweb_server_name script to the <PROFILE_HOME>/bin directory of the deployment manager machine, Machine A. Start the deployment manager and then execute the script.

    2. When the web server is defined to WAS, plugin-cfg.xml is generated automatically. For the IBM HTTP Server, the new plug-in file is propagated to the web server automatically. For other web server types, propagate the new plug-in configuration file to the web server.

    3. Start the web server, and verify the configuration by accessing an application from a web client.

      The plug-in configuration file is generated automatically and is propagated at the next node synchronization.


    Configure a remote web server in a distributed environment

    Assume the Installation Manager, deployment manager, and application server are all installed and configured. The IBM HTTP Server and web server plug-in are also installed.

    To configure a remote web server in a distributed environment using the Web Server Plug-ins Configuration Tool:

    1. Launch the stand-alone WebSphere Customization Toolbox.

    2. Select the Web Server Plug-ins Configuration Tool and then click Launch Selected Tool.

    3. Select a plug-in runtime location. Click Add in the Web Server Plug-in Runtime Locations tab.

      1. Enter a name for the plug-in location.
      2. Browse to the location of where the plug-in is installed.

      Click Finish.

    4. Add the web server configuration information. In the Web Server Plug-in Configurations area, click Create.

    5. Select the web server to configure, and click Next.

    6. Select the existing HTTP Server configuration file and provide the web server port. See

    7. If you are configuring an IBM HTTP web server plug-in:

      1. Enter a port number for the administration server. Keep the default of 8008 or enter a unique port.

      2. Create a user ID for the administration server authentication. The user ID is ihsadmin and the Password is ihsadmin.

      3. Provide a unique user ID and group for web server administration. The user ID and Group is ihs.

    8. Specify a unique name for the web server definition.

    9. Select the remote scenario configuration. Provide a host name or IP address of the application server or deployment manager.

    10. On the Summary window, review the settings, and click Configure.

    11. When the configuration is complete, clear the Launch the plug-in configuration roadmap check box, and click Finish. Also note the manual configuration step that must be performed.

    12. We can see the configuration file in the WebSphere Customization Toolbox. Exit the WebSphere Customization Toolbox. When the WebSphere Customization Toolbox GUI is used for the plug-in configuration, the selections made are saved and are available in a response file.

      Alternative: An alternative to using the WebSphere Customization Toolbox GUI is to use the WebSphere Customization Toolbox command-line utility, which can be used with a response file to configure a web server.

    13. The Web Server Plug-ins Configuration Tool creates the configureweb_server_name script in the plugins_root/bin/ directory on the machine with the web server. Examine the script and make any needed changes. You might need to compensate for file encoding differences to prevent script failure.

      The Web Server Plug-ins Configuration Tool also creates the plugin-cfg.xml file in the

        plugins_root/config/web_server_name directory.

    14. Copy the configureweb_server_name script in the plugins_root/bin/ directory to PROFILE_HOME/Dmgr/bin.

      If one platform is a system, such as AIX or Linux, and the other is a Windows platform, copy the script from the plugins_root/bin/crossPlatformScripts directory.

    15. Run the configureweb_server_name script. If administrative security is enabled, provide the -username and -password arguments or wait until prompted for the credentials.

    16. Log in to the dmgr console, and verify the configuration. Click...

        System administration | Nodes


    Working with web servers and plug-ins

    The introduction of web server definitions to the WAS administrative tools provides the following administrative features:

    • Defining nodes (distributed server environment)
    • Defining and modifying web servers
    • Checking the status of a web server
    • Start and stop IBM HTTP Servers
    • Administering IBM HTTP Servers
    • Viewing or modifying the web server configuration file
    • Mapping modules to servers


    Manually defining nodes and web servers

    A managed node is added to the cell as part of the process when you federate an application server profile or custom profile to the cell. An unmanaged node, however, is not created using a profile. As we have seen, the web server definition script created by the Web Server Plug-ins Configuration Tool defines an unmanaged node for a web server.

    However, there might be times when you need to define or update the definitions using the dmgr console.


    Add an unmanaged node to the cell

    To add an unmanaged node using the dmgr console:

    1. In the console navigation tree, click System administration | Nodes.

    2. Click Add Node.

    3. Select Unmanaged node.

    4. Click Next.

    5. Enter the following values in the General Properties window.

      1. Name: Type a logical name for the node. The name must be unique within the cell. A node name usually is identical to the host name for the computer. However, we can make the node name different than the host name.

      2. Host Name: Enter the host name of the unmanaged node added to the configuration.

      3. Platform Type: Select the operating system on which the unmanaged node runs. Valid options are:

    6. Click OK. The node is added, and the name is displayed in the collection on the Nodes page.


    Add a web server

    After the node for the web server is defined, we can add the web server definition. To add a web server definition:

    1. Click...

        Servers | Web servers

    2. Click New.

    3. Select the node, and enter the web server name. Using the drop-down menu, select the web server type.

    4. Select a template. Initially, this template is the one supplied with WebSphere specific to the web server type. After you define a web server, we can make it a template for future use.

    5. Enter the properties for the web server. You also need to enter the parameters required for remote administration.

    6. Review the options, and click Finish.


    View the status of a web server

    The web server status is reflected in the dmgr console. To view web servers and their statuses:

    1. Click...

        Servers | Web servers

      If a web server is started or stopped using a native command, we might need to refresh the view by clicking the icon to see the new status.

      WAS reports server status using the web server host name and port definedd. This is normally port 80. Do not use the remote administration port. If Use secure protocol is defined, SSL is used.


    Start and stop a web server

    We can start or stop a web server using either the dmgr console or a command window.

    From the dmgr console

    We can start or stop the following web servers from the WebSphere dmgr console:

  • All web servers on a managed node

    The node agent is used to start or stop the web server.

  • IBM HTTP Server on an unmanaged node

    The IBM HTTP Server administration must be running on the web server node.

    To start or stop a web server from the dmgr console:

    1. Click...

        Servers | Web servers

    2. Select the check box to the left of each web server to start or stop.

    3. Click Start or Stop.

      If we have problems starting or stopping an IBM HTTP Server, check the WebSphere console logs (trace) and, if using the IBM HTTP administration server, check the admin_error.log file.

      If we have problems starting and stopping IBM HTTP Server on a managed node using the node agent, we can try to start and stop the server by setting up the managed profile. After setting up the profile, issue the startserver <IBM HTTP Server> -nowait -trace command and check the startServer.log file for the IBM HTTP Server specified.

      From a command window

      We can also use the native startup or shutdown procedures for the supported web server. From a command window, change to the directory of your IBM HTTP Server installed image or to the installed image of a supported web server.

      We can use one of the following two ways to start or stop the web server:

    4. To start or stop the IBM HTTP Server for UNIX platforms, enter one of the following commands at a command prompt:

      • # <ihs_install>/bin/apachectl start
      • # <ihs_install>/bin/apachectl stop

    5. To start or stop the IBM HTTP Server on a Windows platform, select the IBM HTTP Server 8.0 service from the Services window, and invoke the appropriate action.

      When the web server is started or stopped with the native methods, the web server status on the web servers page of the dmgr console is updated accordingly.


    IBM HTTP Server remote administration

    We can administer and configure IBM HTTP Server V8.0 using the WebSphere dmgr console. On a managed node, administration is performed using the node agent. This is true of all web server types. However, unlike other web servers, administration is possible for an IBM HTTP Server installed on an unmanaged node. In this case, administration is done through the IBM HTTP administration server. This server must be configured and running. Administration is limited to generation and propagation of plugin-cfg.xml.


    Remote administration set up

    For the dmgr console to access the IBM HTTP administration server, define a valid user ID and password to access the IBM HTTP Server administration server.

    The user ID and password are stored in the web server's IBM HTTP Server administration server properties.

    We can update your IBM HTTP Server administration server properties in the web server definition through the Remote Web server management properties window of the dmgr console.

    To set or change these properties:

    1. Click...

        Servers | Web servers

    2. Select the name of the web server.

    3. In the Additional Properties section, click Remote Web server management.

    4. Enter the remote web server management information.

      1. Enter the port number for the IBM HTTP Server administration server. The default is 8008.

      2. Enter a user ID and password that are defined to the IBM HTTP administration server.

        The IBM HTTP administration server user ID and password are not verified until you attempt to connect.

      3. Select the Use SSL option, if the port is secure. The default is not set.

    5. Click OK, and save the configuration.

      Setting the user ID and password in the IBM HTTP administration server: The IBM HTTP administration server is set, by default, to refer to the following file to get the user ID and passwords to use for authentication:

        <ihs_install>/conf/admin.passwd

      To initialize this file with a user ID, use the htpasswd command. Example 13-1 initializes the file with the user ID webadmin: 

      /opt/IBM HTTP Server/bin$ ./htpasswd.sh /opt/IBM HTTP Server/conf/admin.passwd" webadmin

New password: ******
Re-type new password: ******

Adding password for user webadmin

      When you are managing an IBM HTTP Server using the WebSphere dmgr console, ensure the following conditions are met:

      • Verify the IBM HTTP Server administration server is running.

      • Verify the web server host name and port defined in the dmgr console match the IBM HTTP Server administration host name and port.

      • Verify the firewall is not preventing you from accessing the IBM HTTP Server administration server from the WebSphere dmgr console.

      • Verify the user ID and password specified in the WebSphere dmgr console under the Remote Web server management is an authorized combination for IBM HTTP Server administration.

      • If you are trying to connect securely, verify that you exported the IBM HTTP Server administration server keydb personal certificate into the WebSphere key database as a signer certificate. This key database is specified by the com.ibm.ssl.trustStore in the sas.client.props file in the profile your console is running. This setup is mainly for self-signed certificates.

      • Verify the IBM HTTP Server admin_error.log file and the WAS logs (trace.log) do not contain any errors.


    Viewing or modifying the web server configuration file

    The Web Server Plug-ins Configuration Tool automatically configures the web server configuration file with the information necessary to use the plug-in. For example, among the updates made are the lines in Example 13-2 at the bottom of httpd.conf.

    Plug-in configuration location defined in httpd.conf

      LoadModule was_ap22_module /opt/WAS/Plugins/bin/mod_was_ap22_http.so" WebSpherePluginConfig /opt/WAS/Plugins/config/webserver1/plugin-cfg.xml"

    The location the web server expects to find plugin-cfg.xml is specified in these lines. When you generate the web server plug-in configuration from the managed web server, propagate or copy the generated file to this location.

    The web server configuration file is a text file and can be modified or viewed manually with a text editor. We can also view or modify this file using the dmgr console.

    To view or modify the contents of the web server configuration file in the web browser:

    1. Click...

        Servers | Web servers

    2. Select the name of the web server.

    3. In the Additional Properties section, click Configuration File.

    4. Type your changes directly into the window, and click OK. Save the changes.

    If you made changes to the configuration file, restart the web server for the changes to take effect.


    Viewing web server logs

    With remote administration, we can also view the IBM HTTP Server access log and error log.

    To view the logs:

    1. Click...

        Servers | Web servers

    2. Select the name of the web server.

    3. In the Additional Properties section, click Log file.

    4. Click the Runtime tab.

    5. Beside the log to view, click View.


    Map modules to servers

    Each module of an application is mapped to one or more target servers. The target server can be an application server, cluster of application servers, or a web server. Modules can be installed on the same application server or dispersed among several application servers. Web servers, specified as targets, have routing information for the application generated in plugin-cfg.xml for the web server.

    This mapping takes place during application deployment. After an application is deployed, we can view or change these mappings. To check or change the mappings:

    1. Click Applications | Application Types | WebSphere enterprise applications.

    2. Click the application for which to review the mapping.

    3. Click Manage modules in the Modules section.

    4. The Select server window opens. Examine the list of mappings. Ensure that each Module entry is mapped to all targets identified under Server.

    5. To change a mapping:

      1. Select each module you want mapped to the same targets by selecting the box to the left of the desired module.

      2. From the Clusters and Servers list, select one or more targets. Use the Ctrl key to select multiple targets. For example, to have a web server serve the application, use the Ctrl key to select an application server and the web server together.

    6. Click Apply.

    7. Repeat step 5 until each module maps to the desired targets.

    8. Click OK, and save your changes.

    9. Regenerate and propagate the plug-in configuration, if it is not done automatically.

    After you define at least one web server, specify a web server as a deployment target whenever you deploy a web application. If the web server plug-in configuration service is enabled, a web server plug-in's configuration file is automatically regenerated whenever a new application is associated with that web server.


    Working with plugin-cfg.xml

    The plug-in configuration file (plugin-cfg.xml) contains routing information for all applications mapped to the web server. This file is read by a binary plug-in module loaded in the web server. An example of a binary plug-in module is the mod_ibm_app_server_http.dll file for IBM HTTP Server on the Windows platform.

    The binary plug-in module does not change. However, plugin-cfg.xml for the binary module needs to be regenerated and propagated to the web server whenever a change is made to the configuration of applications mapped to the web server. The binary module reads the XML file to adjust settings and to locate deployed applications for the web server. Example 13-3 shows an excerpt from a generated plug-in configuration file.

    An except from the plugin-cfg.xml 

    <?xml version="1.0" encoding="ISO-8859-1"?><!--HTTP server plugin config file for the webserver ITSOCell.wan.webserver1 generated on 2004.10.29 at 03:32:12 PM
BST-->
<Config ASDisableNagle="false" AcceptAllContent="false"
AppServerPortPreference="HostHeader" ChunkedResponse="false" FIPSEnable=”false”
FailoverToNext=”false” HTTPMaxHeaders=”300” IISDisableNagle="false"
IISPluginPriority="High" IgnoreDNSFailures="false"
OS400ConvertQueryStringToJobsCCSID=”false” RefreshInterval="60"
ResponseChunkSize="64" SSLConsolidate=”true” TrustedProxyEnable=”false”
VHostMatchingCompat="false">


<Log LogLevel="Error"

Name="c:\opt\WebSphere\Plugins\logs\webserver1\http_plugin.log"/>
<Property Name="ESIEnable" Value="true"/>
<Property Name="ESIMaxCacheSize" Value="1024"/>
<Property Name="ESIInvalidationMonitor" Value="false"/>
<Property Name="ESIEnableToPassCookies" Value="false"/>
<Property Name="PluginInstallRoot" Value="c:\opt\WebSphere\Plugins\*"/>

<VirtualHostGroup Name="default_host">
<VirtualHost Name="*:9080"/>
<VirtualHost Name="*:80"/>
<VirtualHost Name="*:9443"/>

</VirtualHostGroup>

<ServerCluster CloneSeparatorChange="false"GetDWLMTable=”false”
IgnoreAffinityRequests=”true” LoadBalance="Round Robin"
Name="server1_NodeA_Cluster" PostBufferSize=”64” PostSizeLimit="-1"
RemoveSpecialHeaders="true" RetryInterval="60">

<Server ConnectTimeout="0" ExtendedHandshake="false" MaxConnections="-1"

Name="NodeA_server1" WaitForContinue="false">
<Transport Hostname="wan" Port="9080" Protocol="http"/>
<Transport Hostname="wan" Port="9443" Protocol="https">

 <Property Name="keyring"
Value="c:\opt\WebSphere\Plugins\etc\plugin-key.kdb"/>
<Property Name="stashfile"
Value="c:\opt\WebSphere\Plugins\etc\plugin-key.sth"/>
</Transport>
</Server>
</ServerCluster>

<UriGroup Name="default_host_server1_NodeA_Cluster_URIs">
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/snoop/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"
Name="/hello"/>

</UriGroup>
<Route ServerCluster="server1_NodeA_Cluster"
UriGroup="default_host_server1_NodeA_Cluster_URIs"
VirtualHostGroup="default_host"/>
</Config>

    The specific values for the UriGroup Name and AffinityCookie attributes depend on how you assembled the application. Keep the following points in mind when you assemble your application:

    • If we specify File Serving Enabled, only a wildcard URI is generated, regardless of any explicit servlet mappings.

    • If we specify Serve servlets by class name, a URI of the form URI name = <webappuri>/servlet/ is generated.

    Both of these options apply for both the Name and AffinityCookie attributes.

    When plugin-cfg.xml is generated, it does not include admin_host in the list of virtual hosts.


    Regenerating plugin-cfg.xml

    The plug-in configuration file needs to be regenerated and propagated to the web servers when there are changes to your WebSphere configuration that affect how requests are routed from the web server to the application server. The following list shows the included changes:

  • Installing an application

  • Creating or changing a virtual host

  • Creating a new server

  • Modifying HTTP transport settings

  • Creating or altering a cluster

    The plug-in file can be regenerated manually using the administration tools. We can also set up the plug-in properties of the web server to enable automatic generation of the file whenever a relevant configuration change is made. Refer to “Enabling automated plug-in regeneration” on page 506 for more information.

    To regenerate the plug-in configuration manually, we can either use the administrative console, or we can issue the GetPluginCfg command. Generating the plug-in with the dmgr console

    To generate or regenerate plugin-cfg.xml:

    1. Click...

        Servers | Web servers

    2. Select the check box to the left of the web server.

    3. Click Generate Plug-in.

    4. Verify the generation was successful by looking at the messages. A success message is accompanied with the location of the generated plug-in configuration file:

      <PROFILE_HOME>/config/cells/<cellname>/nodes/<web_server_node>/servers/<web_se rver>/plugin-cfg.xml

    5. Click the name of the web server. We can view plugin-cfg.xml by clicking the View button next to the Plug-in configuration file name on the Plug-in properties window of the web server definition. We can also open it with a text editor.

      To use the new plugin-cfg.xml file, propagate it to the web server system.


    Regenerating the plug-in with the GenPluginCfg command

    The GenPluginCfg command is used to regenerate plugin-cfg.xml. Depending on the operating platform, the command is:

    • On UNIX: GenPluginCfg.sh

    • On Windows: GenPluginCfg.bat

    We can use the -profileName option to define the profile of the Application Server process in a multi-profile installation. The -profileName option is not required for running in a single profile environment. The default for this option is the default profile. For a distributed server environment, the default profile is the deployment manager profile.

    Syntax

    The GenPluginCfg command reads the contents of the configuration repository on the local node to generate the Web server plug-in configuration file.

    The syntax of the GenPluginCfg command is:

      :GenPluginCfg.bat(sh) [options]

    All options are optional.

    Options for GenPluginCfg

    Option Description
    -config.root <config root> Directory path of the particular configuration repository to be scanned. The default is the value of CONFIG_ROOT defined in the SetupCmdLine.bat(sh) script.
    -profileName <profile> Runs the command against this profile. If the command is run from WAS_HOME/bin and -profileName is not specified, the default profile is used. If it is run from <PROFILE_HOME>/bin, that profile is used.
    -cell.name <cell name> Restricts generation to only the named cell in the configuration repository. The default is the value of WAS_CELL defined in the SetupCmdLine.bat(sh) script.
    -node.name <node name> Restricts generation to only the named node in the particular cell of the configuration repository. The default is the value of WAS_NODE defined in the SetupCmdLine.bat(sh) script.
    -webserver.name <webserver1> Required for creating plug-in configuration file for a given web server.
    -propagate yes/no Applies only when the option webserver.name is specified. The default is no.
    -propagateKeyring yes/no Applies only when the option webserver.name is specified. The default is no.
    -cluster.name <cluster_name,cluster_name> | ALL Generates an optional list of clusters. It is ignored when the option webserver.name is specified.
    -server.name <server_name, server_name> Generates an optional list of servers. It is required for single server plug-in generation. It is ignored when the option webserver.name is specified.
    -output.file.name <filename> Defines the path to the generated plug-in configuration file. The default is <configroot_dir>/plugin-cfg.xml file. It is ignored when the option webserver.name is specified.
    -destination.root <root> Installation root of the machine on which the configuration is used. It is ignored when the option webserver.name is specified.
    -destination.operating.system windows/unix

    Specifies the operating system of the machine on which the configuration is used. It is ignored when the option webserver.name is specified.

    Option Description -force yes An optional argument to overwrite the existing configuration file. The default is no. -debug <yes | no> Enables or disables the output of debugging messages. The default is no (debugging is disabled). -help or -? Prints the command syntax.

    Examples

    To generate a plug-in configuration for all of the clusters in a cell, run:

      GenPluginCfg -cell.name NetworkDeploymentCell

    To generate a plug-in configuration for a single server, run:

      GenPluginCfg -cell.name BaseApplicationServerCell -node.name appServerNode -server.name appServerName

    To generate a plug-in configuration file for a web server, run:

      GenPluginCfg -cell.name BaseApplicationServerCell -node.name webserverNode -webserver.name webserverName

    When this command is issued without the option -webserver.name webservrName, plugin-cfg.xml is generated based on the topology.


    Enabling automated plug-in regeneration

    The web server plug-in configuration service, by default, regenerates the plugin-cfg.xml file automatically. We can view or change the configuration settings for the web server plug-in configuration service. To view or change the plug-in generation property:

    1. Click...

        Servers | Web servers

    2. Click the name of the web server.

    3. In the Additional Properties section, select Plug-in properties.

    4. View or change the Automatically generate plugin-cfg.xml option


    Plug-in properties

    When selected, the web server plug-in configuration service automatically generates plugin-cfg.xml whenever the web server environment changes. For example, plugin-cfg.xml is regenerated whenever one of the following activities occurs: – A new application is deployed on an associated application server. – The web server definition is saved. – An application is removed from an associated application server. – A new virtual host is defined. Whenever a virtual host definition is updated, plugin-cfg.xml is automatically regenerated for all of the web servers. By default, this option is automatically selected. If you clear the check from the box, you must manually generate a plug-in configuration file for this web server.


    Propagating plugin-cfg.xml

    After a plug-in configuration file is regenerated, it needs to be propagated to the web server.

    The configuration service can automatically propagate the plugin-cfg.xml file to a web server machine if it is configured on a managed node, and to an IBM HTTP Server if it is configured on an unmanaged node. For other scenarios, manually copy the file to the web server machines.

    We can manually propagate the file by copying it from the application server machine to the web server machine, or we can do it from the dmgr console. From a command window

    To copy the file from one machine to another machine:

    1. Copy the file from its original location, for example: <PROFILE_HOME>/config/cells/<cellname>/nodes/<web_server_node>/servers/<web_server>/plugin-cfg.xml

    2. Place the copy in this directory on the remote web server machine: <plug-ins_home>/config/<web_server>

      From the dmgr console

      To propagate the plug-in configuration manually from the dmgr console:

      1. Click...

          Servers | Web servers

      2. Select the check box to the left of the web server.

      3. Click Propagate plug-in.

      4. Verify the propagation was successful by looking at the messages.

        If you are in doubt, check whether plugin-cfg.xml was propagated to the web server plug-in location by viewing it.


      Activating the new plug-in configuration

      The web server binary plug-in module checks for a new configuration file every 60 seconds.

      We can wait for the plug-in to find the changes, or we can restart the web sever to invoke the changes immediately.

      If you encounter problems restarting the web server, check the http_plugin.log file in <plug-ins_home>/config/<web_server> 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.


      Enable automated plug-in propagation

      The web server plug-in configuration service, by default, propagates the plugin-cfg.xml file automatically. To view or change the plug-in propagation property:

      1. Click...

          Servers | Web servers | name of the web server | Additional Properties | Plug-in properties

      2. View or change the option...

          Automatically propagate plug-in configuration file

        By default, this option is automatically selected. If you clear the check box, manually propagate plugin-cfg.xml for this web server.

        To verify the automatic propagation was successful, look in the SystemOut.log file of the deployment manager for details.


    Modifying the plug-in request routing options

    We can specify the load balancing option the plug-in uses when sending requests to the various application servers associated with that web server.

    To view or modify the Request routing:

    1. Click...

        Servers | Web Servers

    2. Click the name of the web server.

    3. In the Additional Properties section, click Plug-in properties.

    4. In the Additional Properties section, click Request Routing.

      • Load balancing option

        This field corresponds to the LoadBalanceWeight element in the plugin-cfg.xml file.

        The load balancing options are covered in detail in WAS V6 Scalability and Performance Handbook, SG24-6392. The following items are short overviews:

      • Round robin (default)

        When using this algorithm, the plug-in selects a cluster member at random from which to start. The first successful browser request is routed to this cluster member and then its weight is decremented by one. New browser requests are then sent round robin to the other application servers and, subsequently, the weight for each application server is decremented by one. The spreading of the load is equal between application servers until one application server reaches a weight of zero. From then on, only application servers without a weight higher than zero receive routed requests. The only exception to this pattern is when a cluster member is added or restarted.

      • Random Requests are passed to cluster members randomly. Weights are not taken into account as in the round robin algorithm. The only time the application servers are not chosen randomly is when there are requests with associated sessions. When the random setting is used, cluster member selection does not take into account where the last request was handled, which means that a new request can be handled by the same cluster member as the last request.

      • Retry interval

        The length of time, in seconds, that elapses from the time an application server is marked down to the time the plug-in retries a connection.

        This field corresponds to the ServerWaitforContinue element in the plugin-cfg.xml file. The default is 60 seconds.

      • Maximum size of request content Limits the size of the request content. If limited, this field also specifies the maximum number of bytes of request content allowed for the plug-in to attempt to send the request to an application server.

        This field corresponds to the PostSizeLimit element in the plugin-cfg.xml file. When a limit is set, the plug-in fails any request received greater than the specified limit.

        We can set a limit in kilobytes or no limit. The default is set to no limit for the post size.

      • Maximum buffer size used when reading HTTP request content

        Maximum buffer size in kilobytes used when the content of an HTTP request is read. If the application server that initially receives a request cannot process that request, the data contained in this buffer is sent to another application server in an attempt to have that application server process the request.

        This field corresponds to the PostBufferSize element in the plugin-cfg.xml file. The default is 64 KB.

      • Remove special headers

        When enabled, the plug-in removes any headers from incoming requests before adding the headers the plug-in is supposed to add before forwarding the request to an application server.

        This field corresponds to the RemoveSpecialHeaders element in the plugin-cfg.xml file. The plug-in adds special headers to the request before it is forwarded to the application server. These headers store information about the request that need to be used by the application. Not removing the headers from incoming requests introduces a potential security exposure.

        The default is to remove special headers.

      • Clone separator change

        When enabled, the plug-in expects the plus character (+) as the clone separator.

        This field corresponds to the ServerCloneID element in the plugin-cfg.xml file. Some pervasive devices cannot handle the colon character (:) used to separate clone IDs in conjunction with session affinity. If this field is checked, also change the configurations of the associated application servers so the application servers separate clone IDs with the plus character too.


    IBM HTTP Server and Web Server Plug-ins for IBM WAS for z/OS

    The installation process for IBM HTTP Server and Web Server Plug-ins for IBM WAS for z/OS can be accomplished by running some jobs and setting configurations on the operating system. In this section, we demonstrate how it can be done.


    IBM HTTP Server

    Before installing IBM HTTP Server for z/OS, you need the following items:

  • Installation Manager: If we do not have Installation Manager installed and operational

  • Product repository: If we do not have your repository available.

    The installation process for IBM HTTP Server is similar to the one used to install WAS.

    After installing IBM HTTP Server for z/OS, configure one instance.


    Web Server Plug-ins for IBM WAS for z/OS

    If we do not have your repository available

    The installation process for Web Server Plug-Ins for IBM WAS for z/OS is similar to the one used to install WAS,


    Configure Web Server Plug-Ins for IBM WAS for z/OS

    1. Create a configuration directory for plug-in, for example, /etc/websrv1.

    2. Go to the plug-in installation root directory.

    3. Create a runtime location directory for the plug-in containing configuration information to be used by the plug-in. When running under a web server instance, use the install_plugin.sh script.

      shows a sample execution where the following parameters were used: -pluginInstallLocation The directory where the plug-in code is installed -pluginRuntimeLocation The directory where the plug-in configuration is created. -wasInstallLocation The directory where the WAS code is installed.

      Creating the plug-in configuration directory 

      /opt/zWebSphere_Plugins/V8R0/bin: >./install_plugin.sh -pluginInstallLocation
/opt/zWebSphere_Plugins/V8R0 -pluginRuntimeLocation /etc/websrv1/Plugins -wasInstallLocation /opt/zWebSphere/V8R0



      Using the plug-in install location /opt/zWebSphere_Plugins/V8R0.



      Using the plug-in runtime location /etc/websrv1/Plugins.



      Using the WAS install location /opt/zWebSphere/V8R0.
#============================================#
Show the install_plugin.sh cmdline args
Plugin Install Location=/opt/zWebSphere_Plugins/V8R0
Plugin Runtime Location=/etc/websrv1/Plugins
WAS Install Location =/opt/zWebSphere/V8R0
#============================================#
The install_plugin.sh has finished "/etc/websrv1/Plugins" is the Plugin runtime location #=================================================#

    4. Go tothe bin subdirectory from the directory you created in step 3 on page 511 or from the plug-in installation directory.

    5. Configure the web server instance to use the plug-in by running the ConfigureIHSPlugin.sh script. Shows a sample execution where the following parameters were used:

      -plugin.home The directory where the plug-in code is installed.
      -plugin.config.xml The location where plugin-cfg.xml will be created.
      -ihs.conf.file The location of the IBM HTTP Server config file.
      -operating.system The operating system where there configuration is being performed.
      -WAS.webserver.name The web server name defined in the WAS configuration.
      -WAS.host.name The WAS host name or IP address.


    Configuring a web server instance to use the plug-in

    1. Run the plugin configuration script... 

      > cd /SYSTEM/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 WTSC58.ITSO.IBM.COM
WSVR0615W: The user.install.root system property is not set. Some product classes might not be found.
Buildfile: /etc/websrv1/Plugins/config/actionRegistry/actions/99SBootStrapPluginsIHS.ant 
bootstrapPluginsIHS:
detectCurrentOSFamily: 
setOSFileSeparator: 
defineOSSpecificConfigFlag:
SetBitsDir: ${is.thirtytwo} 
logStartupProperties: 
updateLogFile: getPlatformPluginDriver:
logBoth: /etc/websrv1/Plugins/bin/mod_was_ap22_http.so
updateLogFile: chkInstall_Arch:
logBoth: updateLogFile:
terminateOnFailure:
checkPlgCfg:
logBoth:
updateLogFile:
terminateOnFailure:
updatePlgCfg:
logBoth: /etc/websrv1/Plugins/config/webserver1
updateLogFile:
createCfgDir:
logBoth:
updateLogFile:
changeCfgDirPerms:
updatePlgKeyStore:
logBoth: /etc/websrv1/Plugins/config/webserver1 
updateLogFile: 
updatePluginCfgGroupOwnerShip:
checkConfigFiles:
logBoth: 
updateLogFile:
terminateOnFailure:
chkLogDir:
logBoth: 
updateLogFile:
createLogDir:
logBoth: 
updateLogFile:
changePluginLogFileOwner: 
nobodyIfNotZOS:
appendIHSConfigurationFileLoadModuleEntry:
e2a_for_zos:
logBoth: 
updateLogFile:
logBoth: 
updateLogFile:
appendToGivenFileGivenString:
appendToGivenFileGivenString:
logBoth: /etc/websrv1/Plugins/bin/mod_was_ap22_http.so to/etc/websrv1/conf/httpd.conf
updateLogFile:
appendToGivenFileGivenString:
logBoth: /etc/websrv1/Plugins/config/webserver1/plugin-cfg.xml to /etc/websrv1/conf/httpd.conf
updateLogFile:
a2e_for_zos:
ConfigureIHSPlugin:
logBoth: 
updateLogFile:
BUILD SUCCESSFUL
Total time: 7 seconds

    2. If you are not using the standard ports for a web server (80 and 443), change them under a virtual host. At the WAS console, click Environment | Virtual hosts, and define your IBM HTTP Server ports to the proper virtual host.

    3. Click...

        Servers | New server

      ...and create the web server definition generated during step 5 on page 512.

    4. Save the configuration, and restart the application server.

    5. Click...

        Servers | Server Types | Web servers | web_server | Propagate Plug-in

    6. Restart the web server.


    Troubleshooting some common errors

    After completing all of the configuration steps, check that all configurations are correct and tested by accessing the application url or sample an application.

    There can be many types of errors, and the following list shows the most common errors you encounter:

    • Error 404 “Page cannot be found”
    • Error 500 “Internal Server Error”


    Troubleshooting Error 404

    When you attempt to access a URL and receive error 404 (page cannot be found):

    1. Check the WebSphere administration console to verify if the virtual hosts entry has the appropriate http port (for example 8080). This can be verified by selecting...

        Environment | Virtual Hosts | default_host

    2. If port 8080 is missing, click New, and add the port. Process the following steps:

      1. Restart the deployment manager.
      2. Regenerate the plug-ins.
      3. Propagate the plug-ins.
      4. Refresh the web servers.
      5. Check the URL again.

      If port 8080 is present in the virtual hosts list, then do the following steps:

      1. Regenerate the plug-ins.
      2. Propagate the plug-ins.
      3. Restart the web servers.

      Plug-ins do not always have information about the application or the virtual hosts, and re-generating the plug-ins can resolve the issue.


    Troubleshooting Error 500

    When you receive error 500 (internal server error), it means the web server cannot reach the application server. There are multiple reasons this can occur. We explore the most common two reasons:

  • The JVM web server is not working. To troubleshoot this issue, the following steps are suggested:

    1. Identify which JVM web server is trying to access from $IHS_HOME/logs/error_log

    2. In the WebSphere administration console, select Servers | Server Types | WAS. Check to see if the JVM web server is down. If it is down, select the JVM web server, and click Start.

    3. The port is not connected or blocked at the firewall level.

    To troubleshoot this issue, the following steps are suggested:

    1. Go to Servers | Server Types | WAS.
    2. Click server, and select ports.
    3. Check the wc_defaulthost port, exampled as 9081.
    4. From the web server, run telnet WAS_SERVER_IP 9081. The port shows if it is connected.

    If it does not show connected, it might be blocked at the firewall level.