WAS v8.5 > Set up intermediary services


Implement a web server plug-in

  1. Overview
  2. Affinity requests
  3. Failover
  4. Peristence
  5. Install architecture
  6. Properties set via console
  7. Configuration service
  8. Appserver property settings
  9. Configuration properties set via dmgr console
  10. plugin-cfg.xml
  11. Set up a local web server
  12. Create a web server definition in the default profile
  13. Set up a remote web server
  14. Web server definition
  15. Edit the web server type
  16. Web servers
  17. Install IHS
  18. Create web server templates
  19. Allow web servers to access the dmgr console
  20. Web server plug-ins
  21. Install and configure web server plug-ins
  22. Create or update a global web server plug-in configuration file
  23. Configure simple load balancing across multiple application server profiles
  24. Configure simple load balancing across multiple application server profiles with an administrative agent
  25. Configure load balancing across multiple appserver profiles with an administrative agent
  26. Transport chains
  27. Configure the web server plug-in for Secure Sockets Layer
  28. Allow web servers to access the dmgr console
  29. Web server plug-in remote user information processing
  30. Run multiple web server child processes
  31. Create or update a global web server plug-in configuration file
  32. Gskit install images files
  33. Programming model and examples
  34. Tuning tips
  35. Private headers


Overview

Web servers use plugins to forward traffic received from browsers to to web applications running on application servers. The configuration file for plugins, generated on the appserver, and residing on the webserver, is plugin-cfg.xml. We generate plugin-cfg.xml on the appserver...

...and then propagate plugin-cfg.xml from the appserver to the webserver...

Web server plug-ins enable the web server to communicate requests for dynamic content, such as servlets, to the application server. A web server plug-in is associated with each web server definition. The configuration file (plugin-cfg.xml) generated for each plug-in is based on the applications that are routed through the associated web server.

A web server plug-in is used to forward HTTP requests from a supported web server to an application server. Using a web server plug-in to provide communication between a web server and an application server has the following advantages:

Each of the supported web server plug-ins runs on a number of operating systems.

The default behavior for the web server plug-in is to buffer requests up to 64 kilobytes, and retry the requests if there is no response from the application server. To ensure high availability, and the HTTP requests tend to be large, set the Maximum buffer size used when reading HTTP request content property on the web server plug-in request routing property page in the dmgr console to -1. Setting this property to -1 removes the maximum buffer size limit, and enables the web server plug-in to buffer all requests regardless of their size. Requests are retried if the request body fits within the buffer size. To disable all request buffering, and thereby disable retries of requests with request bodies, we can set this property to 0.

  • Affinity requests

    Affinity requests are requests containing a JSESSIONID. Session affinity means that all requests of the same JSESSIONID are sent to the same application server. For example, if the initial request is sent to clone5, then the next affinity request from that same browser is also sent to clone5 regardless of the weight valued specified for the LoadBalanceWeight property in plugin-cfg.xml.

    If we select Round robin for the Load balancing option Web server plug-in request routing property, and leave the IgnoreAffinityRequests property in plugin-cfg.xml set to its default value of true, the affinity requests do not lower the weight. This behavior might cause an uneven distribution of requests across the servers in environments that make use of session affinity. Setting the IgnoreAffinityRequests property to false causes the weight to be lowered every time an affinity request is received, which results in a more balanced round robin environment.

    If we select Random for the Load balancing option property, affinity requests are still sent to the same cloneid, but new requests are routed randomly, and the value specified for the LoadBalanceWeight property is ignored.

  • Failover

    If a request connection exceeds the time limit specified on the ConnectTimeout property in plugin-cfg.xml file, or a 5xx error is returned from the application server, the web server plug-in marks the server as down, and attempts to connect to the next application server in the list of primary servers specified for the PrimaryServers property in plugin-cfg.xml file. If the web server plug-in successfully connects to another application server, all requests that were pending for the down application server are sent to this other application server. All other new and affinity requests are sent to other servers, based on whether round robin or random is the setting for the Load balancing option Web server plug-in request routing property.

    Failover typically does not occur the first time the time limit specified on the ServerIOTimeout property in plugin-cfg.xml is exceeded for either a request or a response. Instead, the web server plug-in tries to resend the request to the same application server, using a new stream. If the time specified on the ServerIOTimeout property is exceeded a second time, the web server plug-in marks the server as unavailable, and initiates the failover process.

    Sending a large number of pending requests to the same application server might impact the performance of that application server if a failover situation occurs. We can use the MaxConnections property to limit the number of requests that might be pending for an application server.


    Persistence

    The web server plug-ins are used to establish and maintain persistent HTTP and HTTPS connections to application servers. When the plug-in is ready to send a request to the application server, it first checks its connection pool for existing connections. If an existing connection is available the plug-in checks its connection status. If the status is still good, the plug-in uses that connection to send the request. If a connection does not exist, the plug-in creates one. If a connection exists but has been closed by the application server, the plug-in closes that connection and opens a new one.

    A connection is is closed when the application server closes it for one of the following reasons:

    • Use Keep-Alive is selected and the time limit specified on Read timeout or Write timeout for the HTTP inbound channel has expired.
    • Maximum number of persistent requests which can be processed on an HTTP inbound channel has been exceeded on the HTTP inbound channel.
    • The appserver is shutting down.

    If the application server closes a connection, the plug-in will not know that it has been closed until it tries to use it again. The connection will be closed if one of the following events occur:

    • The plug-in receives a new HTTP request and tries to reuse the existing connection.

    • The number of httpd processes drop because the web server is not receiving any new HTTP requests. For IHS, the number of httpd processes that are kept alive depends on the value specified on the web server's MinSpareServers directive.

    • The web server is stopped and all httpd processes are terminated, and their corresponding sockets are closed.

    Sometimes, if a heavy request load is stopped or decreased abruptly on a particular application server, a lot of the plug-in's connections to that application server will be in CLOSE_WAIT state. Because these connections will be closed the first time the plug-in tries to reuse them, having a large number of connections in CLOSE-WAIT state should not affect performance


    Install architecture

    To determine which the web server architecture, for Apache-based web servers...

      apachectl -V | grep Architecture

    Value will be either 32-bit or 64-bit.

    For non-Apache based web servers...

      file /usr/bin/httpd

    ...which generates...

    • For a 64-bit web server: httpd: 64-bit XCOFF executable ...

    • For a 32-bit web server: httpd: executable (RISC System/6000)...

    In general, if the output of the file command does not indicate 64 in the output, then the application is 32-bit application.

    For Windows, open the Microsoft Windows Task Manager when the server is running and locate the server in the process list. A 32-bit application has *32 after its name.

    If the web server application uses a 64-bit architecture, the plug-in library should be loaded at the bottom of httpd.conf...

      plugin_root/bin/64bit

    If the web server application uses a 32-bit architecture, the plug-in library should be loaded...

      plugin_root/bin/32bits

    If plugin_root/bin/64bits does not exist, use the 32-bit architecture.

    If there is a firewall between the web server plugin and the application server, verify all relevant ports have been opened...

      telnet hostname port


    Web server plug-in properties

    To view or change the settings of a web server plug-in configuration file.

      Servers | Server Types | Web servers | web_server_name | Plug-in Properties | Configuration tab

    Properties include

    Ignore DNS failures during web server startup When true, the plug-in ignores DNS failures and starts successfully if at least one server in each ServerCluster is able to resolve the host name. The server is marked unavailable for the continued existence of the configuration and further attempts to resolve the host name are not made during the routing of requests. If a DNS failure occurs, a message is written to the plug-in log file and the plug-in initialization process continues. Corresponds to IgnoreDNSFailures in plugin-cfg.xml. Default: false
    Refresh configuration interval Time interval, in seconds, at which the plug-in should check the configuration file to see if updates or changes have occurred. The plug-in checks the file for any modifications that have occurred since the last time the plug-in configuration was loaded. Set lower in development, higher in production. Default: 60 seconds.
    Plug-in configuration file name Plug-in configuration file name. This field is disabled and displayed for information purposes only. Default: plugin-cfg.xml
    Automatically generate plug-in configuration file If checked, and plug-in configuration service is enabled, plugin-cfg.xml is automatically generated for a web server whenever:

    When plugin-cfg.xml is generated, it does not include admin_host on the list of virtual hosts. Default: Checked

    Automatically propagate plug-in configuration file The web server administration server must be started...

      cd IHS_HOME/bin
      adminctl start

    Because the plug-in configuration service runs in the background and is not tied to the dmgr console, the dmgr console cannot show the results of the automatic propagation. To verify the automatic propagation successfully completed, check...

      PROFILE_HOME/logs/dmgr/SystemOut.log
    Plug-in key store file name Fully qualified directory path and file name of the database file containing the security key rings the Web server plug-in uses for HTTPS requests. This file resides on the Web server associated with this web server plug-in.

    To update, click...

      Manage keys and certificates

    To add a copy of this file to the key store directory for the web server, click...

      Copy to web server key store directory
    Plug-in configuration directory and file name Fully qualified path of the web server copy of the web server plug-in configuration file. This path is the name of the file and its location on the machine where the web server is running.

    This field is disabled and cannot be changed, but the value is displayed for information purposes only.

    Plug-in key store directory and file name Fully qualified path of the web server copy of the database file containing the security key rings. This path is the name of the file and its location on the machine where the web server is running.

    This field is disabled and cannot be changed, but the value is displayed for information purposes only.

    Plug-in logging Set location for http_plugin.log file. Default is:

      plugins_root/logs/web_server_name/http_plugin.log

    Also set level of log messages written by the plug-in. If we change LogLevel directly in plugin-cfg.xml file, restart the web server to pick up the change.

      Trace All of the steps in the request process are logged in detail.
      Stats The server selected for each request and other load balancing information relating to request handling is logged.
      Warn All warning and error messages resulting from abnormal request processing are logged.
      Error Default. Only error messages resulting from abnormal request processing are logged.
      Debug All of the critical steps performed in processing requests are logged.
      Detail All of the information about requests and responses are logged.


    Web server plug-in configuration service property

    To view or change the configuration settings for the web server plug-in configuration service.

    The web server plug-in configuration service is selected by default. The service automatically generates plugin-cfg.xml whenever the web server environment changes, with a few exceptions. 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

    To disable the configuration service while working with web server plug-ins, clear the option...


    Appserver property settings for a web server plug-in

    To view or change application server settings for a web server plug-in

      Servers | Server Types | WebSphere application servers | server_name | Additional Properties | Web server plug-in properties

    Properties include...

    Server Role Primary to add this application server to the list of primary application servers. The plug-in initially attempts to route requests to the application servers on this list. Select Backup to add this application server to the list of backup application servers. The plug-in does not load balance across the backup application servers. A backup server is only used if a primary server is not available. When the plug-in determines that a backup application server is required, it goes through the list of backup servers, in order, until no servers are left in the list or until a request is successfully sent and a response received from one of the servers on this list.

    Connection timeout Whether there is a limited amount of time during which the application server maintains a connection with the web server. Corresponds to ConnectTimeout in plugin-cfg.xml. If not selected, the plug-in performs nonblocking connections with the appserver. Non-blocking connections are beneficial when the plug-in is unable to contact the destination to determine whether or not the port is available. If selected, specify a value in the seconds field:

      > 0 Plug-in waits the specified number for seconds to perform a successful connection. If a connection does not occur during that time interval, the plug-in marks the server unavailable, and sends the request to another application server in the cluster.
      0 The plug-in performs a blocking connection.
      No value Plug-in performs a blocking connection where the plug-in sits until the operating system times out, which might be as long as two minutes, depending on the platform, before it marks the server unavailable.

    Default is 0 for the first application server (server1) of a profile, and 5 for all of the other application servers of a profile.

    Use read/write timeout Whether there is a time limit for how long the plug-in waits to send a request to or receive a response from the application server. This field corresponds to the ServerIOTimeout element in plugin-cfg.xml file. When selected, specify the length of time, in seconds the plug-in waits to send a request or to receive a response. It might take a couple of minutes for an application server to process a request. Setting the value too low might cause the plug-in to send a false server error response to the client. If the checkbox is not checked, the plug-in uses blocked I/O to write requests to and read responses from the application server until the TCP connection times out. Default is 900 seconds
    Use maximum number of connections Maximum number of pending connections to an appserver that can be flowing through a web server process at any point in time. This field corresponds to the ServerMaxConnections element in plugin-cfg.xml. If set to either zero or -1, there is no limit to the number of pending connections to the appservers. Default is 0.

    Use extended handshake to check whether application server is running Select if a proxy firewall is between the plug-in and the application server. The plug-in marks a server as down when the connect() fails. However, when a proxy firewall is in between the plug-in and the application server, the connect() will succeed, even though the back end application server is down. This causes the plug-in to not failover correctly to another application server. If the plug-in performs some handshaking with the application server to ensure the application server is started before the plug-in sends a request, the plug-in can failover to another application server if it detects the application server with which it is attempting to perform a handshake is not available. By default, this field is not selected. Corresponds to the ExtendedHandshake element in plugin-cfg.xml.

    Send the header "100 Continue" before sending the request content Corresponds to the WaitForContinue element in plugin-cfg.xml file. When selected, the web server plug-in sends the header "100 Continue" to the application server before it sends the request content. By default, this field is not selected. Select this field to enable this function.


    Web server plug-in configuration properties set via dmgr console

    Administrative console panel Field name Configuration property
    Servers | Server Types | Web servers | web_server_name | Plug-in properties Refresh configuration interval RefreshInterval
    Servers | Server Types | Web servers | web_server_name | Plug-in properties Plug-in log file name Log-|name
    Servers | Server Types | Web servers | web_server_name | Plug-in properties Plug-in logging Log-|LogLevel
    Servers | Server Types | Web servers | web_server_name | Plug-in properties Ignore DNS failures during web server startup IgnoreDNSFailures
    Servers | Server Types | Web servers | web_server_name | Plug-in properties KeyringLocation Keyring
    Servers | Server Types | Web servers | web_server_name | Plug-in properties StashfileLocation Stashfile
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Custom properties | New FIPSEnable FIPSEnable
    Servers | Web Servers | Web_server_name | Plug-in properties | Custom properties | New TrustedProxyEnable TrustedProxyEnable
    Servers | Web Servers | Web_server_name | Plug-in properties | Custom properties | New TrustedProxyList TrustedProxyList
    Servers | Web Servers | Web_server_name| Plug-in properties | Custom properties | New SSLConsolidate SSLConsolidate
    Servers | Web Servers | Web_server_name| Plug-in properties | Custom properties | New SSLPKCSDriver SSLPKCSDriver
    Servers | Web Servers | Web_server_name| Plug-in properties | Custom properties | New SSLPKCSPassword SSLPKCSPassword
    Servers | Server Types | Web servers | Web_server_name | Plug-in properties | Request routing Load balancing option LoadBalance
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request Routing Clone separator change CloneSeparatorChange
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request Routing Retry interval RetryInterval
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request routing Maximum size of request content PostSizeLimit
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request routing Size of the buffer used to cache POST requests PostBufferSize
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request routing Remove special headers RemoveSpecialHeaders
    Servers | Server Types | WebSphere application servers | server_name | Web server plug-in properties Server role PrimaryServers and BackupServers list
    Servers | Server Types | WebSphere application servers | server_name | Web server plug-in properties Connect timeout Server ConnectTimeout
    Servers | Server Types | WebSphere application servers | server_name>Web server plug-in properties. The read and write timeouts for all the connections to the application server ServerIOTimeout
    Servers | Clusters | WebSphere application servers clusters | server_name, > Web server plug-in cluster properties. The number of retries for the application server. ServerIOTimeoutRetry
    Servers | Server Types | WebSphere application servers | server_name | Web server plug-in properties Use extended handshake to check whether an appserver is running. Server Extended Handshake
    Servers | Server Types | WebSphere application servers | server_name | Web server plug-in properties Send the header "100 Continue" before sending the request content WaitForContinue
    Servers | Server Types | WebSphere application servers | server_name | Web server plug-in properties Maximum number of connections that can be handled by the appserver Server MaxConnections
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request and Response Application server port preference AppServerPortPreference
    Servers | Web Servers | Web_server_name | Plug-in properties | Request and Response Enable Nagle algorithm for connections to the appserver ASDisableNagle
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request and Response Enable Nagle Algorithm for the IIS Web Server IISDisableNagle
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request and Response Virtual host matching VHostMatchingCompat
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request and Response Maximum chunk size used when reading the response body ResponseChunkSize
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request and Response Accept content for all requests AcceptAllContent
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request and Response Chunk HTTP response to the client ChunkedResponse
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Request and Response Priority used by the IIS Web Server when loading plugin-cfg.xml IISPluginPriority
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Caching Enable Edge Side Include (ESI) processing to cache the responses ESIEnable
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Caching Maximum cache size ESIMaxCacheSize
    Servers | Server Types | Web servers | web_server_name | Plug-in properties | Caching Enable invalidation monitor to receive notifications ESIInvalidationMonitor
    Servers | Web Servers | Web_server_name | Plug-in properties | Custom properties | New Forwarding of session cookies to WebSphere Application Server. ESIEnableToPassCookies


    plugin-cfg.xml file

    We can update the plugin-cfg.xml file using the dmgr console or by running GenPluginCfg for all of the clusters in a cell. If we have a global plugin-cfg.xml, in config/cells/plugin-cfg.xml, delete it first before regenerating.

    plugin-cfg.elements include...

    • Config
    • IgnoreDNSFailures
    • RefreshInterval
    • ASDisableNagle
    • IISDisableNagle
    • VHostMatchingCompat
    • AppServerPortPreference
    • ResponseChunkSize
    • AcceptAllContent
    • ChunkedResponse
    • Log
    • Property Name=esiEnable Value=true/false
    • Property Name=esiMaxCacheSize Value=integer
    • Property Name=ESIInvalidationMonitor Value=true/false
    • Property Name=FIPSEnable Value=true/false
    • Property Name=PluginInstallRoot Value=/opt/IBM/Plugins
    • ServerCluster
    • VirtualHostGroup
    • UriGroup
    • Route
    • RequestMetrics

    Use the dmgr console to generate new plugin-cfg.xml files for each web server definition. Any manual changes made to plugin-cfg.xml on each web server will be overwritten whenever the file is regenerated.

    If plugin-cfg.xml exists within...

      app_server_root/dmgr/cells

    ...the plug-in generation process ignores the updated values from...

      Application server | Web Server Plugin Properties

    ...and uses the existing values within the XML file. In this case, manually update the XML file for those values to persist.

    If plugin-cfg.xml does not exist within...

      app_server_root/dmgr/cells

    ...the plug-in generation process creates a new plugin-cfg.xml file and persists the latest values.


    plugin-cfg.xml elements and attributes

    Config

    Required. Starts the HTTP plug-in configuration file.


    IgnoreDNSFailures

    Whether the plug-in ignores DNS failures within a configuration when starting. When set to true, the plug-in ignores DNS failures within a configuration and starts successfully if at least one server in each server cluster is able to resolve the host name. Any server for which the host name cannot be resolved is marked unavailable for the life of the configuration. No attempts to resolve the host name are made during the routing of requests. If a DNS failure occurs, a log message is written to the plug-in log file, and the plug-in initialization continues rather than causing the web server not to start. Default is false, meaning DNS failures cause the web server not to start.


    RefreshInterval

    Time interval, in seconds, at which the plug-in checks the configuration file to see if updates or changes have occurred. The plug-in checks the file for any modifications that have occurred since the last time the plug-in configuration was loaded.

    In a development environment in which changes are frequent, a lower setting than the default setting of 60 is preferable. In production, a higher value than the default is preferable because updates to the configuration do not occur so often. If the plug-in reload fails for some reason, a message is written to the plug-in log file and the previous configuration is used until plugin-cfg.xml successfully reloads. If we are not seeing the changes you made to the plug-in configuration, check the plug-in log file for indications of the problem.


    ASDisableNagle

    Tue will disable the nagle algorithm for the connection between the plug-in and the application server. Default is false.

    IISDisableNagle

    Whether the user wants to disable the nagle algorithm on Microsoft Internet Information Services (IIS). By default, the nagle algorithm is enabled.

    The value can be true or false.


    VHostMatchingCompat

    The port number is to be used for virtual host matching. Specify one of the following values:

    • true if matching is to be done physically using the port number for which the request was received.
    • false if matching is to be done logically using the port number contained in the host header.

    Default is false.


    AppServerPortPreference

    Which port number the application server uses to build URIs for a sendRedirect() method. The following values can be specified:

    • hostHeader if the port number from the host header of the HTTP request coming in is to be used.
    • webserverPort if the port number on which the web server received the request is to be used.

    Default is hostHeader.


    ResponseChunkSize

    Maximum chunk size to use when reading the response body. For example, specify Config ResponseChunkSize="N">, where N equals the chunk size in kilobytes.

    The plug-in reads the response body in 64 K chunks until all of the response data is read. This approach causes a performance problem for requests whose response body contains large amounts of data.

    If the content length of the response body is unknown, a buffer size of N KBs is allocated and the body is read in N KB size chunks, until the entire body is read. If the content length is known, then a buffer size of either content length or N (whichever is less) is used to read the response body.

    The default chunk size is 64 K.


    AcceptAllContent

    Whether users can include content in POST, PUT, GET, and HEAD requests when a Content-Length or Transfer-encoding header is contained in the request header. We can specify one of the following values for this attribute:

    • True if content is expected and read for all requests
    • False if content is only expected and read for POST and PUT requests.

    Default is True.


    ChunkedResponse

    Whether the plug-in must use chunks the response to the client when a Transfer-Encoding: Chunked response header is present in the response.

    This attribute applies to the IIS, Oracle iPlanet, and Lotus Domino web servers only. The IBM HTTP Server automatically handles the chunking of the response to the client.

    We can specify one of the following values for this attribute:

    • true if the plug-in is to chunk the response to the client when a Transfer-Encoding: Chunked response header is present in the response.
    • false if the response is not to be chunked.

    Default is false.


    TrustedProxyEnable

    Permits the web server plug-in to interface with the proxy servers and load balancers listed for the TrustedProxyList custom property. When true, the proxy servers and load balancers in this trusted proxy list can set values for the $WSRA and $WSRH internal headers. The $WSRA internal header is the IP address of the remote host, which is typically the browser, or an internal address that is obtained by Network Address Translation (N.A.T.). The $WSRH internal header is the host name of the remote host. This header information enables the web server plug-in to interface with that specific proxy server or load balancer.

    When we use this custom property you must also use the TrustedProxyList custom property to specify a list of trusted proxy servers and load balancers. Also, you must clear the Remove special headers check box on the Request Routing panel within the dmgr console. For more information, see the documentation on web server plug-in request routing properties.


    TrustedProxyList

    Comma delimited list of all proxy servers or load balancers that have permission to interface with this web server plug-in. You must use this property with the TrustedProxyEnable=true custom property setting. If the TrustedProxyEnable custom property is set to false, this list is ignored.


    SSLConsolidate

    Whether the web server plug-in is to compare the setup of each new SSL transport with the setup of other SSL transports that are already defined in the configuration file. When you set this property to true, and the plug-in determines the keyring and CertLabel values specified for the new SSL transport match the values specified for an already defined SSL transport, the plug-in uses the existing SSL environment instead of creating a new SSL environment. Creating fewer SSL environments means the plug-in requires less memory, and the plug-in initialization time decreases, thereby optimizing the overall GSkit environment.


    SSLPKCSDriver

    Fully qualified name of the loadable module that interfaces with an optional SSL co-processor. The fully qualified name must include the directory path and the module name.


    SSLPKCSPassword

    Password for the SSL co-processor with which the module, specified for the SSLPKCSDriver custom property, is interfacing.

    If we are using an IHS, we can use the sslstash program to create a file containing this password. In this situation, we can specify the fully-qualified name of that file, instead of the actual password, as the value for this custom property.


    Log

    Location and level of log messages that are written by the plug-in. If a log element is not specified within the configuration file, then, in some cases, log messages are written to the web server error log.

    For example, you might specify the following line of code:

      <Log LogLevel="Error" Name="/opt/WebSphere/AppServer60/logs/http_plugin.log"/>

    • Name

      Fully qualified path to the log file to which the plug-in writes error messages. Specify exactly one attribute for each log.

      If the file does not exist, then one is created. If the file exists, then it is opened in append mode, and the previous plug-in log messages remain.

    • LogLevel

      Level of detail of the log messages the plug-in writes to the log. Specify zero or one of the following values for each log.
      Log Level Value Log Level Description
      Trace All of the steps in the request process are logged in detail.
      Stats The server selected for each request and other load balancing information relating to request handling is logged.
      Warn All warning and error messages resulting from abnormal request processing are logged
      Error Only error messages resulting from abnormal request processing are logged
      Debug All of the critical steps performed in processing requests are logged.
      Detail All of the information about requests and responses are logged.

      If a LogLevel value is not specified for the Log element, the default value, Error, is used.

      Be careful when setting the level to Trace. Multiple messages are logged at this level, which can consume disk space quickly. Do not use a Trace setting in a normally functioning environment because it adversely affects performance.


    Property Name="esiEnable" Value="true/false"

    Enables or disables the Edge Side Include (ESI) processor. If the ESI processor is disabled, the other ESI elements in this file are ignored. We can set Value to true or false. By default, the ESI processor is enabled with its value set to true.


    Property Name="esiMaxCacheSize" Value="integer"

    Specifies, in 1 KB units, the maximum size of the cache. The default maximum size of the cache is 1024 KB (1 MB). If the cache is full, the first entry deleted from the cache is the entry that is closest its expiration time.


    Property Name="ESIInvalidationMonitor" Value="true/false"

    Whether the ESI processor receives invalidations from the application server.

    We can set Value to true or false. By default, this property is set to false.


    Property Name="FIPSEnable" Value="true/false"

    Whether the Federal Information Processing Standard (FIPS) is enabled for making SSL connections to the application server. Set to true, if FIPS is enabled on the application server.

    We can set Value value to true or false. By default, this property is set to false.


    Property Name="PluginInstallRoot" Value="C:\IBM\WebSphere\Plugins"

    Installation path for the plug-in. This property is mandatory if using the Global Security Kit (GSKit) because WebSphere Application Server supports the local installation of the GSKit instead of a global installation. The attribute value is set to a fully qualified path to the plug-in installation root.

    Supported names recognized by the transport are keyring, stashfile, and password. By default, this property is set to none.


    ServerCluster

    Group of servers configured to service the same types of requests. Specify one or more clusters for each configuration. In the simplest case, the cluster contains only one server definition. In the case in which more than one server is defined, the plug-in load balances across the defined servers using either a Round Robin or a Random algorithm. The default algorithm is Round Robin.

    <ServerCluster Name="Servers"> 
        <ClusterAddress Name="ClusterAddr">         <Transport Hostname="192.168.1.2" Port="9080" Protocol="HTTP"/>         <Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS">             <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>             <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>         </Transport>     </ClusterAddress> 
        <Server Name="Server1">         <Transport Hostname="192.168.1.3" Port="9080" Protocol="HTTP"/>         <Transport Hostname="192.168.1.3" Port="9443" Protocol="HTTPS">             <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>             <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>         </Transport>     </Server> 
        <Server Name=Server2>         <Transport Hostname="192.168.1.4" Port="9080" Protocol="HTTP"/>         <Transport Hostname="192.168.1.4" Port="9443" Protocol="HTTPS">             <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>             <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>         </Transport>     </Server> 
        <Server Name="Server3">         <Transport Hostname="192.168.1.5" Port="9080" Protocol="HTTP"/>         <Transport Hostname="192.168.1.5" Port="9443" Protocol="HTTPS">             <Property Name="Keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/>             <Property Name="Stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/>         </Transport>     </Server> 
        <PrimaryServers>         <Server Name="Server1"/>         <Server Name="Server2"/>     </PrimaryServers> 
        <BackupServers>         <Server Name="Server3"/>     </BackupServers> 
    </ServerCluster>

    ...where...

    • Name

      Logical or administrative name to be used for this group of servers. Specify one attribute for each ServerCluster.

    • LoadBalance

      The Round Robin implementation has a random starting point. The first application server is picked randomly. Round Robin is then used to pick application servers from that point forward. This implementation ensures that in multiple process-based web servers, all of the processes do not start by sending the first request to the same appserver. The Random implementation also has a random starting point. However with this implementation all subsequent servers are also randomly selected. Therefore, the same server might get selected repeatedly while other servers remain idle. The default load balancing type is Round Robin.

    • IgnoreAffinityRequests

      Whether the plug-in ignores the number of affinity requests made to a server when selecting servers based on the Round Robin algorithm. Specify zero or one attribute for each ServerCluster. The value is true or false. If the value is set to false, the number of affinity requests made is also taken into account in the server selection process.

      Default is true, which means the number of affinity requests made are not used in the Round Robin algorithm.

      Beginning with WAS v8.5, the default value is false, which means the number of affinity requests made are used in the Round Robin algorithm.trns

    • RetryInterval

      Integer value for the length of time that elapses from the time that a server is marked down to the time the plug-in tries a connection again. The default is 60 seconds. Specify zero or one attribute for each ServerCluster.

    • RemoveSpecialHeaders

      The plug-in adds special headers to the request before it is forwarded to the application server. These headers store information about the request used by the application. By default, the plug-in removes these headers from incoming requests before adding the headers it is supposed to add. Specify zero or one attribute for each ServerCluster. Setting the attribute to false introduces a potential security exposure by not removing headers from incoming requests.

    • CloneSeparatorChange

      Set true to tell the plug-in to expect the plus character (+) as the clone separator. Some pervasive devices cannot handle the colon character (:) used to separate clone IDs in conjunction with session affinity. You must change application server configurations so that an application server separates clone IDs with the plus character as well. Specify zero or one attribute for each ServerCluster.

    • PostSizeLimit

      Maximum number of KBs (1024 byte) blocks of request content allowed for the plug-in to attempt to send the request to an application server. If a request is received that is greater than this size, the plug-in fails the request. Default is -1 byte, which indicates there is no limit for the post size. Specify zero or one attribute for each ServerCluster.

    • PostBufferSize

      Specifies, in KBs, the maximum buffer size 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. It then attempts to have that application server process the request. We can set this option to zero if we do not want requests that have content to be buffered, and then retried.

      This option improves the availability of the plug-in. When this option is set to a non-zero value, any pending packets containing a payload are resent if the selected application server does not respond.

      Typically, POST and PUT requests carry a payload, but other requests might also carry a payload. Even if a POST or PUT request does not have a payload, it is retried if the value specified for this option is not zero.

      Default is 64. Specify zero or one attribute for each ServerCluster.

    • ServerIOTimeoutRetry

      Limit for the number of times the HTTP plugin retries an HTTP request that has timed out, due to ServerIOTimeout. The default value, -1, indicates that no additional limits apply to the number of retries. A 0 value indicates there are no retries. Retries are always limited by the number of available servers in the cluster.

      This directive does not apply to connection failures or timeouts due to the HTTP plug-in ConnectTimeout.

    • Server

      WAS instance configured to handle requests routed to it, based on the routing rules of the plug-in configuration. The server corresponds to an application server running on either the local machine or a remote machine. Specify zero or one attribute for each ServerCluster.

        Name Administrative or logical name for the server. Specify exactly one attribute for each Server.
        WaitForContinue Whether to use the HTTP 1.1 100 Continue support before sending the request content to the application server. Possible attribute values are true or false. The default value is false; the plug-in does not wait for the 100 Continue response from the application server before sending the request content because it is a performance hit. Specify zero or one attribute for each Server. This property is ignored for POST requests to prevent a failure from occurring if the application server closes a connection because of a keep-alive timeout. Enable this function true when configuring the plug-in to work with certain types of proxy firewalls.
        LoadBalanceWeight Weight associated with this server when the plug-in performs weighted Round Robin load balancing. Specify zero or one attribute for each Server. The starting value for a server can be any integer between 0 and 20. However, specify zero only for a server not running. The LoadBalanceWeight value for each server is decremented for each request that is processed by that server. After the weight for a particular server in a server cluster reaches zero, only requests with session affinity are routed to that server. When all servers in the cluster reach a weight of zero, the weights for all servers in the cluster are reset, and the algorithm restarts. Best practice: When a server is not running, set the weight for that server to zero. The plug-in can then reset the weights of the servers that are still running, and maintain proper load balancing.
        ConnectTimeout Enables the plug-in to perform non-blocking connections with the application server. Non-blocking connections are beneficial when the plug-in is unable to contact the destination to determine if the port is available or unavailable. Specify zero or one attribute for each Server. If a ConnectTimeout value is not specified, the plug-in performs a blocking connect in which the plug-in sits until an operating system times out (as long as 2 minutes depending on the platform) and allows the plug-in to mark the server unavailable. A value of 0 causes the plug-in to perform a blocking connect. A value greater than 0 specifies the number of seconds you want the plug-in to wait for a successful connection. If a connection does not occur after that time interval, the plug-in marks the server unavailable and fails over to one of the other servers defined in the cluster. Default is 0 for the first application server (server1) of a profile, and 5 for all of the other application servers of a profile.
        ExtendedHandshake Used when a proxy firewall is between the plug-in and the application server. In such a case, the plug-in is not failing over, as expected. Specify zero or one attribute for each Server. The plug-in marks a server as down when the connect() method fails. However, when a proxy firewall is in between the plug-in and the application server, the connect() method succeeds, even though the back-end application server is down. This causes the plug-in to not failover correctly to other application servers. The plug-in performs some handshaking with the application server to ensure that it is started before sending the request. This scenario enables the plug-in to failover in the event the application server is down. The value can be true or false.
        MaxConnections Maximum number of pending connections to an application server that can be flowing through a web server process at any point in time. Specify one element for each Server. For example, in the following scenario:

        • The application server is fronted by five nodes that are running an IHS.
        • Each node starts two processes.
        • The MaxConnections attribute is set to 50.

        In this example, the application server can potentially get up to 500 connections. Multiply the number of nodes, 5, by the number of processes, 2, and then multiply that number by the number specified for the MaxConnections attribute, 50, for a total of 500 connections. By default, MaxConnections is set to -1. If this attribute is set to either zero or -1, there is no limit to the number of pending connections to the application servers.

        Transport Transport for reading and writing requests to a particular WAS instance. The transport provides the information that is necessary to determine the location of the application server to which the request is sent. If the server has multiple transports that are defined to use the same protocol, the first one is used. Specify one or more elements for each Server. It is possible to configure the server to have one non-secure transport and one that uses SSL. In this configuration, a match of the incoming request protocol is performed to determine the appropriate transport to use to send the request to the application server.

          Hostname Host name or IP address of the machine on which the WAS instance is running.
          Port Port on which the WAS instance is listening.
          Protocol Protocol, http or https, to use when communicating over this transport.

        Property Specify zero, one, or more elements for each transport. When the protocol of the transport is set to HTTPS, use this element to supply the various initialization parameters, such as password, keyring and stashfile. For example, the portion of plugin-cfg.xml containing these elements might look like the following code:
        <Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS"> <Property Name="keyring" value="c:/WebSphere/AppServer/keys/keyring.kdb"/> <Property Name="stashfile" value="c:/WebSphere/AppServer/keys/keyring.sth"/> <Property Name="password" value="WebAS"/>

        ...where...

          Name Name of the property that is being defined. Supported names recognized by the transport are keyring, stashfile, and password. The only name that can be specified for the WebSphere HTTP plug-in for z/OS is password. If we specify keyring and stashfile, they are ignored. Specify exactly one attribute for each Property.
          Value Value of the property being defined. Specify exactly one attribute for each property.

        ServerIOTimeout Enables the plug-in to set a timeout value, in seconds, for sending requests to and reading responses from the application server. If we set the ServerIOTimeout attribute to a positive value, this attempt to contact the server ends when the timeout occurs. However, the server is not considered unavailable and future requests are still sent to the server on which the unavailable timeout occurred. If we set the ServerIOTimeout attribute to a negative value, the server is considered unavailable whenever a timeout occurs, and no future requests are sent to the server on which the timeout occurred. If a value is not set for the ServerIOTimeout attribute, the plug-in, by default, uses blocked I/O to write requests to and read responses from the application server, and does not time out the TCP connection. For example, you might specify the following setting:

        In this situation, if an application server stops responding to requests, the plug-in waits 300 seconds (5 minutes) before timing out the TCP connection. Setting the ServerIOTimeout attribute to a reasonable value enables the plug-in to timeout the connection sooner, and transfer requests to another application server when possible. When selecting a value for this attribute, remember that sometimes it might take several minutes for an application server to process a request. Setting the value of the ServerIOTimeout attribute too low might cause the plug-in to send a false server error response to the client. Default is 900, which is equivalent to 15 minutes. The ServerIOTimeout limits the amount of time the plug-in waits for each individual read or write operation to return. ServerIOTimeout does not represent a timeout for the overall request. For additional recommendations on how to configure the ServerIOTimeout attribute, see the web server plug-in configuration technote on the IBM Support website.

    • ClusterAddress

      Use a ClusterAddress when we do not want the plug-in to perform any type of load balancing because you already have some type of load balancer in between the plug-in and the application server. Contains same attributes and elements as Server element. The difference is that we can define only one of them within a ServerCluster.

      If we include a ClusterAddress tag, you must include the Name attribute on that tag. The plug-in uses the Name attribute to associate the cluster address with the correct host and port. If we do not specify the Name attribute, the plug-in assigns the cluster address the name specified for the server that is using the same host and port.

        <ClusterAddress Name="MyClusterAddr">     <Transport Hostname="192.168.1.2" Port="9080" Protocol="HTTP"/>     <Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS"> </ClusterAddress>

      If a request comes in that does not have affinity established, the plug-in routes it to the cluster address, if defined. If affinity has been established, then the plug-in routes the request directly to the clone, bypassing the cluster address entirely. If no cluster address is defined for the server cluster, then the plug-in load balances across the servers in the primary servers list. There can be zero or one element for each ServerCluster.

    • PrimaryServers

      List of servers to which the plug-in routes requests for this cluster. If a list of primary servers is not specified, the plug-in routes requests to servers defined for the server cluster. Specify zero or one element for each ServerCluster.

    • BackupServers

      List of servers to which requests are sent if all servers specified in the primary servers list are unavailable. The plug-in does not load balance across the backup servers, but traverses the list in order until no servers are left in the list or until a request is successfully sent and a response is received from an application server. Specify zero or one element for each ServerCluster.


    VirtualHostGroup

    Group of virtual host names configured to handle similar types of requests. For example...

    <VirtualHostGroup Name="Hosts">     < VirtualHost Name="www.x.com"/>     <VirtualHost Name="www.x.com:443"/>     <VirtualHost Name="*:8080"/>     <VirtualHost Name="www.x.com:*"/>     <VirtualHost Name="*:*"/>     </VirtualHostGroup>

    ...where...

      Name Logical or administrative name to be used for this group of virtual hosts. Specify exactly one attribute for each VirtualHostGroup.
      VirtualHost If the host name and port in the HTTP Host header of a request sent by a web client to the web server matches the host name and port defined in a VirtualHost, forward incoming request to WebSphere Application Server. We can use an asterisk (*) for the host name, an asterisk for the port, or an asterisk for both. An asterisk for both means that any request matches this rule. If no port is specified in the definition, the default HTTP port of 80 is assumed.


    UriGroup

    Specifies a group of URIs specified on the HTTP request line. The same application server must be able to handle the URIs. The route compares the incoming URI with the URIs in the group to determine if the application server handles the request.

    The following example shows a UriGroup element and associated elements and attributes:

      <UriGroup Name="Uris"> <Uri Name="/servlet/snoop/"> <Uri Name="/webapp/*/"> <Uri Name="*.jsp/"> </UriGroup>

    • Name

      Logical or administrative name for this group of URIs. Specify exactly one attribute for each UriGroup.

    • Uri

      Virtual path to the resource that is serviced by WAS. Each URI specifies the incoming URLs the application server needs to handle. We can use a wildcard in these definitions. There can be one or more attributes for each UriGroup.

      • Name

        Actual string to specify in the HTTP request line to match successfully with this URI. We can use a wildcard within the URI definition. We can specify rules such as *.jsp or /servlet/* to be handled by WAS. When you assemble the application, if we specify File Serving Enabled, then only a wildcard URI is generated for the web application, regardless of any explicit servlet mappings. If we specify Serve servlets by classname, then the following URI is generated: <Uri Name="Web_application_URI/servlet/*">

        There is exactly one attribute for each URI.

      • AffinityCookie

        Name of the cookie the plug-in uses when trying to determine if the inbound request has session affinity. Default is JSESSIONID.

        There can be zero or one attribute for each URI.

      • AffinityURLIdentifier

        Name of the identifier the plug-in uses when trying to determine if the inbound request has affinity specified in the URL to a particular clone. Default is jsessionid.

        There can be zero or one attribute for each URI.


    Route

    Request routing rule by which the plug-in determines if an incoming request must be handled by WAS.

    The route definition is the central element of the plug-in configuration. It specifies how the plug-in handles requests, based on certain characteristics of the request. The route definition contains the other main elements: a required ServerCluster, and either a VirtualHostGroup, UriGroup, or both.

    Using the information defined in the VirtualHostGroup and the UriGroup for the route, the plug-in determines if the incoming request to the web server is sent on to the ServerCluster element defined in this route.

    Example of this element:

      <Route VirtualHostGroup="Hosts" UriGroup="Uris" ServerCluster="servers"/>

    • VirtualHostGroup

      Group of virtual hosts used in route determination. The incoming host header and server port are matched to determine if this request is handled by the application server.

      It is possible to omit this property from the route definition. If it is not present, then every request matches during the virtual host match portion of route determination.

      There can be zero or one attribute for each Route.

    • UriGroup

      Specifies the group of URIs to use for determining the route. Select zero or one group for each route. The incoming URI for the request is matched to the defined URIs in this group to determine whether this request is handled by the application server.

      It is possible to omit this property from the route definition. If it is not present, then every request matches during the URI match portion of route determination.

    • ServerCluster

      Cluster that receives the requests that successfully matches the route. Select exactly one cluster for each route.

      The cluster is used to handle this request. If both the URI and the virtual host matching is successful for this route, then the request is sent to one of the servers defined within this cluster.


    RequestMetrics

    Used to determine whether request metrics are enabled, and how to filter the requests based on the Internet Protocol (IP) and Uniform Resource Identifiers (URI) filters when request metrics are enabled.

    Example of this element:

    <RequestMetrics armEnabled="false"  loggingEnabled="true"
       rmEnabled="false" traceLevel="PERF_DEBUG">

    • armEnabled

      Whether the ARM 4 agent is enabled in the plug-in. When it is set to true, the ARM 4 agent is called.

      For the SunOne (iPlanet) web Server the following directive must be included in the obj.conf file to enable ARM 4 support:

        AddLog fn="as_term"
      If this directive is not included, the arm_stop procedure is never called.

      Select zero or one attribute for RequestMetrics

    • loggingEnabled

      Whether request metrics logging is enabled in the plug-in. When it is set to true and the traceLevel is not set to NONE, the request response time, and other request information, is logged. When it is set to false, there is no request logging. The value of loggingEnabled depends on the value specified for the system property, com.ibm.websphere.pmi.reqmetrics.loggingEnabled. When this system property is not present, loggingEnable is set to true. Specify exactly one attribute for RequestMetrics.

    • rmEnabled

      Whether the request metrics are enabled in the plug-in. When it is set to true, the plug-in, request metrics, inspects the filters and logs the request trace record in the plug-in log file. This action is performed if a request passes the filters. When this attribute is set to false, the rest of the request metrics attributes are ignored. Specify exactly one attribute for RequestMetrics.

    • traceLevel

      Indicates how much information is logged when the rmEnabled attribute is set to true. When this attribute is set to NONE, no request logging is performed. When this attribute is not set to NONE, and loggingEnabled is set to true, the request response time, and other request information, is logged when the request is done. Specify exactly one attribute for RequestMetrics.

    • filters

      When rmEnabled is true, the filters control which requests are traced. Specify zero, one, or two attributes for RequestMetrics.

      • enable

        When enable is true, the type of filter is on and requests must pass the filter. Specify exactly one attribute for each filter.

      • type

        There are two types of filters: SOURCE_IP (for example, client IP address) and URI. For the SOURCE_IP filter type, requests are filtered based on a known IP address. We can specify a mask for an IP address using the asterisk (*). If the asterisk is used, the asterisk must always be the last character of the mask, for example 127.0.0.*, 127.0.*, 127*. For performance reasons, the pattern matches character by character, until either an asterisk is found in the filter, a mismatch occurs, or the filters are found as an exact match.

        For the URI filter type, requests are filtered based on the URI of the incoming HTTP request. The rules for pattern matching are the same as matching SOURCE_IP address filters.

        If both URI and client IP address filters are enabled, request metrics require a match for both filter types. If neither is enabled, all requests are considered a match.

        There is exactly one attribute for each filter.

      • filterValues

        Detailed filter information. Specify one or multiple attributes for each filter.

        • value

          Filter value for the corresponding filter type. This value might be either a client IP address or a URI. Specify exactly one attribute for each filterValue.

      • ESIEnableToPassCookies

        Whether to allow forwarding of session cookies to WAS when processing ESI include requests. If the value is set to true, this custom property is enabled. If the value is set to false, the custom property is disabled. By default, the value is set to false.

      • GetDWLMTable

        Whether to allow a newly created plug-in process to proactively request a partition table from WAS before it handles any HTTP requests. This custom property is used only when memory-to-memory session management is configured. If the value is set to true, this custom property is enabled. If the value is set to false, the custom property is disabled. By default, the value is set to false.


    Set up a local web server

    If we are setting up and IHS, and you plan to manage that web server through a node agent running as a nonroot user, verify you adhere to the following requirements:

    • The user ID that you designate as the user ID that owns the IHS directories and files, is the same user ID under which the nonroot node agent is running. We cannot run an IHS as a root user if the node agent that is managing that IHS is running as nonroot node agent because a node agent process running as a nonroot user cannot spawn off an IHS running as a root user.

    • The value specified for the listener port value must be greater than 1024. An IHS running under a nonroot user ID does not start if the port number for its listener port is 1024 or less.

    We can ensure the nonroot node agent and the IHS are using the same user ID if we specify the user ID that we used to install the product as the user ID for the IHS when we install the IHS. However, if, you decide to run the node agent as a nonroot user after you install the IHS and web server plug-in, we can take the following actions to enable both the node agent and the IHS to run as nonroot users:

    1. Change the user ID for WAS to a nonroot user ID.

    2. Configure the run-as setting for the node agent.

    3. Use the dmgr console to create a new IBM HTTP Web Server, unless an already defined IHS has the required properties.

    4. Change the ownership of the IHS directory and files to the nonroot user ID under which the nonroot node agent is running.


    Create a web server definition in the default profile

    1. From installation media, install Installation Manager, WAS, IHS, web server plug-ins, and the WebSphere Customization Toolbox (wct.sh).

    2. Create an application server profile and federate node to dmgr

    3. From the web server, using wct.sh, configure the web server definition script

    4. Copy generated script to appserver and execute to create a web server definition.

      Assign the web server to a managed node when we create it. The managed node must exist before running the Web Server Plug-ins Configuration Tool. Otherwise, the installation is considered a remote installation.

      Select one of the following options:

      • Use the dmgr console.

        Create a web server definition on an existing application server.

        1. Click Servers > Server Types > Web servers > New and use the Create new web server definition tool to create the web server definition.

        2. Select a template. Select a system template or a user-defined template for the web server to create.

        3. Enter the web server properties:

          Type The web server vendor type
          Port The existing web server port (default: 80)
          Installation path Web server installation path. Required for IHS only.
          Service name (Windows) Windows OS service name of the web server. The default is IBMHTTPServer7.0.
          Use secure protocol Use HTTPS. The default is HTTP.
          Plug-in installation location Directory path in which the plug-in is installed.

        4. Confirm the creation of the new web server, and click Finish.

        After creating the web server...to verify the plugin-key.kdb file is generated and to configure the web server plug-in with SSL:

        1. Click...

            Security | SSL certificate and key management | Configuration settings | Manage endpoint security configurations | Inbound or Outbound | cell_name | nodes | Web_server_node_name | servers | server_name | Related Items | Key stores and certificates

          The dmgr console displays the CMSKeyStore configuration with the path to the plugin-key.kdb file.

        2. Export the default certificate from key.p12, and add it as a signer certificate to the plugin-key.kdb.

      • Run the plug-in configuration script.


    Set up a remote web server

    Steps to create a web server definition in the default profile...

    1. Install IBM Installation Manager, WAS, IHS, web server plug-ins, WebSphere Customization Toolbox.

    2. Configure the web server plug-in using the Web Server Plug-ins Configuration Tool.

    3. Create the web server definition.

      • Using dmgr console:

        1. Click...

            Servers | Server Types | Web servers | New

          ...and enter web server properties...

          Type The web server vendor type.
          Port The existing web server port. The default is 80.
          Installation Path The web server installation path. This field is required field for IHS only.
          WINDOWS Service Name The Windows operating system service name of the web server. The default is IBMHTTPServer7.0.
          Use secure protocol Use the HTTPS protocol to communicate with the web server. The default is HTTP.
          Plug-in installation location The directory path where the plug-in is installed.
          Application mapping to the web server Whether to create a mapping to existing applications that are currently deployed to the web server. Select ALL if you want the mapping created; select None if we do not want the mapping created. If we have enterprise applications in different security domains when we create a web server, the Key Database (KDB) files for the security configuration might not be created if we have Application mapping to the web server set to All. To resolve this problem, create the web server with Application mapping to the web server set to None. Then map the applications to the web server. All the KDB files for the web server are then created.

        2. Enter the remote web server properties. The properties for the IHS administration server follow:

            Port The administration server port. The default is 8008.
            User ID The user ID that is created using the htpasswd script.
            Password The password that corresponds to the user ID created with the htpasswd script.
            Use secure protocol Communicate with the administration server. The default is HTTP.

          • Select a web server template. Select a system template or a user-defined template for the web server to create.

          • Confirmation of web server creation.

      • Using plug-in configuration script: configurewebserver.sh.

    4. For Unix systems, on the remote web server, run...

      cd /opt/IBM/Portal/HTTPServer/bin
      ./setupadm -usr wasadmin \
                 -grp staff \
                 -cfg /opt/IBM/Portal/HTTPServer/conf/httpd.conf \
                 -adm /opt/IBM/Portal/HTTPServer/conf/admin.conf \
                 -plg /opt/IBM/Portal/Plugins/config/webserver1/plugin-cfg.xml 

      This gives the administration server read and write access to web server configuration data. After running, as user root, run...

        IHS_HOME/bin/adminctl restart
        IHS_HOME/bin/apachectl restart

    5. For AIX, HP-UX, Linux, Solaris, or Windows operating system, on the remote web server, run htpasswd.

      The administration server is installed with authentication enabled and a blank admin.passwd password file . The administration server will not accept a connection without a valid user ID and password. This is done to protect the IHS configuration file from unauthorized access.

        ./htpasswd -cm /opt/IBM/Portal/HTTPServer/conf/admin.passwd wasadmin

    6. Restart IHS.

    7. To test, log on to dmgr, then regenerate and propagate plugin for the web server.

      Propagate should be automatic at this point.


    Web server definition

    To administer or manage a web server using the dmgr console, create a web server definition or object in the WebSphere Application Server repository.

    The creation of this object is exclusive of the actual installation of a web server. The web server object in the WAS repository represents the web server for administering and managing the web server from the dmgr console.

    The web server object contains the following web server properties:

    • installation root
    • port
    • configuration file paths
    • log file paths

    In addition to web server properties, the web server contains a plug-in object. The plug-in object contains properties that define plugin-cfg.xml.

    The definitions of the web server object are made using wsadmin or the dmgr console. We can also define a web server object in the WAS repository using the profile create script during installation, a .jacl script, and using the dmgr console wizard.

    There are three types of WAS nodes upon which we can create a web server. The type depends on the version of WAS, as follows:

    • Managed node.

      A node containing a node agent. This node can exist only in a deployment manager environment. The importance of defining a web server on a managed node is the administration and configuration of the web server is handled through the node agent from the dmgr console. Support for administration and configuration through the dmgr console is limited to IBM HTTP Server only. Non-IHS web servers must be on a managed node to handle plug-in administrative functions and the generation and propagation of plugin-cfg.xml.

    • Stand-alone node

      A node that does not contain a node agent. This node usually exists in WAS (base) or WAS, Express environment. A stand-alone node can become a managed node in a deployment manager environment after the node is federated . A stand-alone node does not contain a node agent, so to administer and manage IHS, there must be an IHS administration server installed and running on the stand-alone machine the node represents. IHS ships with the IHS administration server and is installed by default. Support for administration and configuration through the dmgr console is limited to IHS only.

    • Unmanaged node

      A node not associated with a WAS node agent. This node cannot be federated.

      Typically, the unmanaged node represents a remote machine that does not have WAS installed. However, we can define an unmanaged node on a machine where WAS is installed. This node can exist in aWAS (base), WAS, Express, or deployment manager environment. An unmanaged node does not contain a node agent, so to administer and manage IHS, an IHS administration server must be installed and running on the stand-alone machine the node represents. Support for administration and configuration through the dmgr console is limited to IHS only.

    Web servers, which are not IHSs for WAS, are not fully administered from the WAS dmgr console. The administration functions for Web servers, which are not IHSs for WAS, are:

    • On managed nodes:

      • Web server status in the web server collection panel or serverStatus.sh
      • Generation of the plugin-cfg.xml
      • Propagation of the plugin-cfg.xml

    • On unmanaged nodes:

      • Web server status in the web server collection panel or serverStatus.sh
      • Generation of the plugin-cfg.xml


    Edit the web server type

    This topic provides information on how to change the type of Web server. If we install a web server that is different from the one that is currently installed, we can modify the web server type from IBM HTTP Server to a non-IHS and vice versa, rather than delete the web server and create a new web server definition. If we change the web server type from IHS to non-IHS web server, the administration capabilities are lost accordingly.

    1. From the WebSphere Application Server dmgr console, click Servers > Server Types > Web servers.

    2. Select the server to modify.

    3. On the web server configuration panel, change the web server by selecting an option from the Type drop-down menu. If we are changing from a non-IHS to an IHS, you are also prompted for information such as IHS administration server port, user ID, and IHS administration server password.

    4. Click Apply.

    We can verify the changes on the web servers collection panel. The web server type displays in the Web Server Type column.


    Web servers

    To view this dmgr console page click...

      Servers | Server Types | Web Servers

    To create a new web server, click New to launch the Create new web server entry wizard. To manage an installed web server, select the check box adjacent to the application name in the list and click a button:
    Button Resulting Action
    Generate Plug-in

    When the plug-in configuration service is enabled, plugin-cfg.xml is automatically generated for a web server whenever:

    • The WebSphere Application Server administrator defines new web server.
    • An application is deployed to an appserver.
    • An application is uninstalled.
    • A virtual host definition is updated and saved.

    Propagate Plug-in Choose this action will copy plugin-cfg.xml from the local directory where the appserver is installed to the remote machine. If we are using IHS V6 or higher for the web server, WAS can automatically propagate plugin-cfg.xml to remote machines provided there is a working HTTP transport mechanism to propagate the file.
    New Launches the wizard to create a new web server entry.
    Delete Deletes one or more of the selected web server entries.
    Templates ... Opens the web server templates list panel. From this panel we can create a new template or delete existing templates.
    Start Starts one or more of the selected web servers.
    Stop Stops one or more of the selected web servers.
    Terminate Terminates one or more of the selected web servers.


    Name

    Logical name for the web server. This can be the host name of the machine, or any name you choose.


    Web server type

    Indicates the type of web server you are using.


    Node

    Logical name for the web server. This can be the host name of the machine, or any name you choose.

    Name of the node on which the web server is defined. This column only applies for the WAS, Network Deployment product.


    Version

    Version of the WAS on which the web server is defined.


    Status

    Indicates whether the web server is started, stopped, or unavailable.

    If the status is unavailable, the IHS administration server is not running, and you must start the application server before we can start the web server.

    Status indicators. The following table describes the status indicators.

    Status Indicator Resulting Action Description
    Started The web server is running.
    Stopped The web server is not running.
    Unknown Status cannot be determined. A web server with an unknown status might, in fact, be running but has an unknown status because the application server running the dmgr console cannot communicate with this web server.


    Install IHS

    This article describes how to install IBM HTTP Server.

    Install the IHS product and its plug-in, or install a plug-in for another supported web server to enable the web server to work with WebSphere Application Server.

    To use a web server other than IHS, install and configure the web server before or after installing the WAS product but before installing the Web Server Plug-ins for IBM WAS. Refer to the information center for IHS for detailed information on installation steps, configuring the web server for SSL, the Fast Response Cache Accelerator, or Apache directives.

    After installing the web server and the application server, install and configure the appropriate web server plug-in for a supported, installed web server. No further configuration is required for most web servers.

    The Web Server Plug-ins Configuration Tool configures supported web servers. We can also manually configure supported Web servers for WAS as described in Edit web server configuration files.

    The Global Security Kit (GSKit) installation image files for the WebSphere Web server plug-ins are packaged on the CD with the web server plug-in files. To use GSKIT, we can download the appropriate GSKIT file to the workstation on which the web server is running.


    Create web server templates

    A web server template is used to define the configuration settings for a new web server. When creating a new web server, we can either create a new web server definition or use a previously created web server template based on another, already existing web server. To create a web server template.

    1. In the dmgr console, click...

        Servers | Server Types | Web servers | Templates

      We can also use the createWebServerTemplate command for AdminTask to create a web server template.

    2. On the Server Templates page, click New.

    3. Select the web server to use to create the new template, and then click OK.

    4. Enter the name of the new template and, optionally, a description of that template that distinguishes it from the other templates.

    5. Click OK.

    Your new template displays in the list of server templates used to create a new web server.

    We can perform one of the following actions to display a list of all of the server templates available on the system:

    • In the dmgr console, click...

        Servers | Server Types | Web servers | Templates
    • Issue a listServerTemplates wsadmin command that includes the -serverType WEB_SERVER parameter.


    Allow web servers to access the dmgr console

    This topic describes how to add the virtual host that servers the dmgr console to plugin-cfg.xml so that we can access the dmgr console through a web server.

    Install the WAS product, a web server, the Web Server Plug-ins, and the WebSphere Customization Toolbox.

    The Web Server Plug-ins Configuration Tool creates a web server definition on the application server system, either directly when they are on the same machine or by a script for remote scenarios.

    After creating the web server definition, plugin-cfg.xml exists within the web server definition. This task gives you the option of configuring the admin_host so that web servers can access the dmgr console. When the web server plug-in configuration file is generated, it does not include admin_host on the list of virtual hosts.

    1. Use the dmgr console to change the admin_host virtual host group to include the web server port (80 by default).

      1. Click Environment > Virtual Host > admin_host > Host Aliases > New.

        The default port that displays is 80, unless we specify a different port during installation or profile creation.

      2. Specify the IP address, or the name of the machine that is hosting the HTTP server.

        For example, if you installed a WAS product on a machine that is named waslwaj.rtp.ibm.com, specify the name in this field.

    2. Click Apply > Save.

    3. Stop and restart the application server.

      For example, to access the dmgr console of a stand-alone application server, stop and restart the server1 process.

      To stop server1, open a command window and navigate to the profile_root/bin directory. Then issue the following command:

      After receiving the following message, we can restart the application server:

      To start the application server, issue the following command:

      When you receive a message that is similar to the following message, the server1 process is running.

        Server server1 open for e-business; process id is 1719

    4. Edit plugin-cfg.xml to include the following entries:
      <VirtualHostGroup Name="admin_host">         < VirtualHost Name="*:9060"/>         <VirtualHost Name="*:80"/>         <VirtualHost Name="*:9043"/>     </VirtualHostGroup>     ...
          ...
          ...
          <ServerCluster Name="server1_SERVER1HOSTserver1_Cluster">         <Server LoadBalanceWeight="1" Name="SERVER1HOSTserver1_dmgr">             <Transport Hostname="SERVER1HOST" Port="9060" Protocol="http"/>         </Server>         
              <PrimaryServers>             <Server Name="SERVER1HOSTserver1_dmgr"/>         </PrimaryServers>     </ServerCluster>     ...
          ...
          ...
          <UriGroup Name="admin_host_server1_SERVER1HOSTserver1_Cluster_URIs">         <Uri AffinityCookie="JSESSIONID"
                  AffinityURLIdentifier="jsessionid" Name="/ibm/console/*"/>     </UriGroup>     <Route ServerCluster="server1_SERVER1HOSTserver1_Cluster"
              UriGroup="admin_host_server1_SERVER1HOSTserver1_Cluster_URIs" VirtualHostGroup="admin_host"/>         

      If the HTTP server has an HTTP port other than 80, add an entry to the VirtualHostGroup:

      The port variable is the HTTP server port.

    We can configure the supported web servers to access the dmgr console application of a stand-alone application server.


    Web server plug-ins

    Web server plug-ins enable the web server to communicate requests for dynamic content, such as servlets, to the application server. A web server plug-in is associated with each web server definition. The configuration file (plugin-cfg.xml) generated for each plug-in is based on the applications that are routed through the associated web server.

    A web server plug-in is used to forward HTTP requests from a supported web server to an application server. Using a web server plug-in to provide communication between a web server and an application server has the following advantages:

    • XML-based configuration file
    • Standard protocol recognized by firewall products
    • Security using HTTPS, replacing proprietary Open Servlet Engine (OSE) over SSL

    Each of the supported web server plug-ins runs on a number of operating systems.

    The default behavior for the web server plug-in is to buffer requests up to 64 kilobytes, and retry the requests if there is no response from the application server. To ensure high availability, and the HTTP requests tend to be large, set the Maximum buffer size used when reading HTTP request content property on the web server plug-in request routing property page in the dmgr console to -1. Setting this property to -1 removes the maximum buffer size limit, and enables the web server plug-in to buffer all requests regardless of their size. Requests are retried if the request body fits within the buffer size. To disable all request buffering, and thereby disable retries of requests with request bodies, we can set this property to 0.


    Affinity requests

    Affinity requests are requests containing a JSESSIONID. Session affinity means that all requests of the same JSESSIONID are sent to the same application server. For example, if the initial request is sent to clone5, then the next affinity request from that same browser is also sent to clone5 regardless of the weight valued specified for the LoadBalanceWeight property in plugin-cfg.xml.

    If we select Round robin for the Load balancing option Web server plug-in request routing property, and leave the IgnoreAffinityRequests property in plugin-cfg.xml set to its default value of true, the affinity requests do not lower the weight. This behavior might cause an uneven distribution of requests across the servers in environments that make use of session affinity. Setting the IgnoreAffinityRequests property to false causes the weight to be lowered every time an affinity request is received, which results in a more balanced round robin environment.

    If we select Random for the Load balancing option property, affinity requests are still sent to the same cloneid, but new requests are routed randomly, and the value specified for the LoadBalanceWeight property is ignored.


    Failover

    If a request connection exceeds the time limit specified on the ConnectTimeout property in plugin-cfg.xml file, or a 5xx error is returned from the application server, the web server plug-in marks the server as down, and attempts to connect to the next application server in the list of primary servers specified for the PrimaryServers property in plugin-cfg.xml file. If the web server plug-in successfully connects to another application server, all requests that were pending for the down application server are sent to this other application server. All other new and affinity requests are sent to other servers, based on whether round robin or random is the setting for the Load balancing option Web server plug-in request routing property.

    Failover typically does not occur the first time the time limit specified on the ServerIOTimeout property in plugin-cfg.xml is exceeded for either a request or a response. Instead, the web server plug-in tries to resend the request to the same application server, using a new stream. If the time specified on the ServerIOTimeout property is exceeded a second time, the web server plug-in marks the server as unavailable, and initiates the failover process.

    Sending a large number of pending requests to the same application server might impact the performance of that application server if a failover situation occurs. We can use the MaxConnections property to limit the number of requests that might be pending for an application server.


    Run multiple web server child processes

    We can configure most web servers to start multiple child processes. In this situation, each child process loads its own instance of the web server. When running multiple web server child processes, remember that:

    • Multiple running instances of the web server plug-in cannot share information. Therefore the dynamically changing load balance weight of each application server is not shared between the web server plug-in instances. For example, one instance of the web server plug-in might consider an application server to be running with a weight of 5, while another instance of the web server plug-in might be consider the same application server to be down and unusable. This difference in perspective might cause an incoming request to be handled differently, depending on which web server plug-in instance handles the request.

    • The web server plug-in settings are handled on a per instance basis. For example, the MaxConnections property specifies the number of pending requests allowed on that web server, for each web server plug-in instance. If the MaxConnections property is set to 20, and you start three web server child processes, each of the three web server plug-in instances allow 20 pending connections to the same application server, which means there could be up to 60 pending connections.


    Install and configure web server plug-ins

    WebSphere Application Server supplies a unique binary plug-in module for each supported web server. The plug-in configuration file, which the WAS products create and maintain, interacts with the binary module to provide information about the application server configuration to the web server. The web server uses the information to determine how to communicate with the application server. See Web server plug-in policy for WAS

    You must install a supported web server before we can install and configure a plug-in for the web server.

    The Web Server Plug-ins Configuration Tool configures the web server for communicating with the application server and creates a web server configuration definition in the application server if possible.

    Some topologies, such as the web server on one system and the application server on another system, prevent the Web Server Plug-ins Configuration Tool from creating the web server definition in the application server configuration directly on the remote system. In such a case, the Web Server Plug-ins Configuration Tool creates a script that we can copy to the application server system. Run the script to create the web server configuration definition within the application server configuration.

    The Web Server Plug-ins Configuration Tool is intended for use with the full WAS profile; it is not required or supported for use in generating a web server plug-in for the Liberty profile. For information on generating a web server plug-in for the Liberty profile, read Configure the Liberty profile with web servers plug-in.

    This article describes installing and configuring web server plug-ins for WAS. WAS products supplies a unique binary plug-in module for each supported web server. The plug-in configuration file, which the WAS products create and maintain, interacts with the binary module to provide information about the application server configuration to the web server. The web server uses the information to determine how to communicate with the application server.

    The Web Server Plug-ins Configuration Tool configures the web server and the application server to allow communication between the servers.

    As an alternative to using the Web Server Plug-ins Configuration Tool, we can use the pct command-line tool with a response file to configure a web server. Read Configure a web server plug-in using the pct tool for more information.

    Select one of the following topology scenarios and follow the steps below the diagram to install the plug-in and configure both the web server and the application server. When multiple profiles exist, we can select the profile the Web Server Plug-ins Configuration Tool configures.

    We can install a web server and the web server plug-ins for various standalone application server topologies by following the procedures described in this article.


    Create or update a global web server plug-in configuration file

    If all of the application servers in a cell use the same web server to route requests for dynamic content, such as servlets and portlets.to application servers, we can create a global web server plug-in configuration file for that cell. The resulting plugin-cfg.xml file is located in the profile_root/config/cells directory.

    We can update the global plugin-cfg.xml file using the dmgr console or running the GenPluginCfg command for all of the clusters in a cell. However, you must delete the config/cells/plugin-cfg.xml file before you update the global plugin-cfg.xml file. If we do not delete the config/cells/plugin-cfg.xml file, only the new properties and their values are added to the global plugin-cfg.xml file. Any updates to existing plug-in property values are not added to the global plugin-cfg.xml file. You must update the global web server plug-in configuration file whenever you perform one of the following actions:

    • Change the configuration settings for an application server, cluster, virtual host, or web container transport that is part of that cell.

    • Add a new application server, cluster, virtual host, or web container transport to that cell.

    To update the configuration settings for a global web server plug-in, we can either use the Update global web server plug-in configuration page in the dmgr console, or issue the following command:

      %was_profile_home%/config/cells/GenPluginCfg.sh

    Both methods for regenerating the global web server plug-in configuration create a plugin-cfg.xml file in ASCII format.

    To use the Update global web server plug-in configuration page in the dmgr console:

    1. Click Environment > Update global web server plug-in configuration.

    2. Click OK to update plugin-cfg.xml.

    3. Optional: Click...

        To view or download the current version of this file.

          View or download the current web server plug-in configuration file

        We can select this option to:

        • View the current version of the file before you update it.
        • View the file after it is updated.
        • Download a copy of this file to a remote machine.

    Regenerating the configuration 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. Whether triggered manually or occurring automatically, plug-in regeneration requires about 30 to 60 seconds to complete when the application server is on the same physical machine (node) as the web server. In other cases, it takes more time.

    The delay is important because it determines how soon the new plug-in configuration takes effect. Suppose you add a new served path for a servlet, then regenerate the plug-in configurations. The regeneration requires 40 seconds, after which a user should be able to access the servlet by the new served path.

    For an HTTP plug-in, the length of the delay is determined by the Refresh Interval attribute of the Config element in plugin-cfg.xml. The plug-in polls the disk, or file system, at this interval to see whether the configuration has changed. The default interval is 60 seconds. To regenerate the plug-in configuration requires twice the refresh interval.

    In a development environment in which we are frequently changing settings in the dmgr console, IBM recommends set the refresh interval to 3 to 5 seconds.

    In a production environment, set a longer refresh interval, perhaps as long as 30 minutes, depending on the frequency of changes.

    You might need to stop the application servers in the cell and then start the application servers again before the changes to the plug-in configuration go into effect.

    If the web server is running on a remote machine, to download a copy of plugin-cfg.xml to a that machine, click...

      View or download the current web server plug-in configuration file


    Configure simple load balancing across multiple application server profiles

    Simple load balancing distributes HTTP requests across multiple IBM WebSphere Application Server instances. We can configure simple load balancing to provide failover of an application state that is maintained in an HTTP session.

    This offering applies to stand-alone application server profiles for IBM WAS. This offering does not include a centralized management capability such as the deployment manager in WAS, Network Deployment. We can configure simple load balancing capability with WAS by combining plugin-cfg.xmls of multiple stand-alone application server profiles into a single configuration file. The number of configuration files that we can combine are bound by the limits that exist in the WAS license agreement. We can use the following different configurations of the application server to combine plugin-cfg.xmls of multiple application server profiles into a single output file:

    • Using multiple stand-alone base application server profiles

    • Using multiple stand-alone base application server profiles with an administrative agent. For more information, see the documentation on configuring simple load balancing across multiple stand-alone base application server profiles with an administrative agent.

    • Using multiple stand-alone base application server profiles with an administrative agent using the job manager. The job manager function is a part of WAS, Network Deployment. However, we can use the job manager function with stand-alone, base application server profiles. For more information, see the documentation on configuring simple load balancing across multiple stand-alone, base application server profiles with an administrative agent using the job manager.

    To configure simple load balancing across multiple stand-alone, base application server profiles:

    1. Install WAS and create application server profiles. For more information, see the documentation on WAS installation and application server profiles.

    2. Install the enterprise application or web module. For more information, see the documentation on the methods for installing applications or modules.

    3. Determine if you require session affinity.

      Session affinity directs requests from a given client to a specific application server. The application state maintained in the HTTP session is accessed in the HTTP session cache, which is local to the application server. Session affinity provides higher performance than database persistence of the session object, alone. Without session affinity, session requests must be obtained from the database if they are sent to a server that does not have the session object in the local cache.

    4. Optional: Configure a unique HTTP session clone ID for each application server. Complete this step if you require session affinity.

      We can configure a unique HTTP session clone ID using wsadmin scripting or the dmgr console. To use wsadmin commands for the Jython or Jacl programming language, see the documentation on configuring a unique HTTP session clone ID for each application server using scripting. To configure a unique HTTP session clone ID using the dmgr console, complete the following steps:

      1. Expand Servers > Server Types and click WebSphere application servers > server_name.

      2. Under Container Settings, expand Web Container Settings, and click Web container.

      3. Under Additional Properties, click Custom properties > New.

      4. In the Name field, enter HttpSessionCloneId.

      5. In the Value field, enter a unique value for the server. The unique value must be 8 - 9 alphanumeric characters; for example, test1234

      6. Click Apply or OK.

      7. Click Save to save the configuration changes to the master configuration.

    5. Optional: Configure session persistence, if needed. If we require session failover capability, configure session persistence. Persistence of the session object to a database is the only option for session failover with WAS. To configure session persistence using the dmgr console, see the documentation on configuring database session persistence. To configure database session persistence using wsadmin commands for the Jython or Jacl programming language, see the documentation on configuring database session persistence using scripting.

    6. Restart the server.

    7. Generate plugin-cfg.xml for each application server using the GenPluginCfg script, the dmgr console, or wsadmin scripting.

    8. Merge plugin-cfg.xmls from multiple application server nodes.

      We can either manually merge plugin-cfg.xmls or use the pluginCfgMerge tool to automatically merge plugin-cfg.xml from multiple application server profiles into a single output file. The pluginCfgMerge.bat and pluginCfgMerge.sh files are located in the install_root/bin directory.

      To use the pluginCfgMerge tool...

      1. Rename plugin-cfg.xmls to a unique name across the application server profiles.

      2. Copy plugin-cfg.xml for all stand-alone application server profiles into a common directory.

      3. Use the pluginCfgMerge tool to combine plugin-cfg.xmls from each of the application server profiles into a single output file. For example:

          install_root/bin/pluginCfgMerge.sh plugin_configuration_file1 plugin_configuration_file2 resulting_plugin_configuration_file

          install_root\bin\pluginCfgMerge.bat plugin_configuration_file1 plugin_configuration_file2 resulting_plugin_configuration_file

        The resulting_plugin_configuration_file variable value is normally plugin-cfg.xml

      For more information about manually merging plugin-cfg.xmls, see the technote on merging plugin-cfg.xml files from multiple application server profiles.

    9. Copy the merged plugin-cfg.xml file to the plugin_installation_root/config/web_server_name/ directory on the web server host.

      Ensure that we have defined the correct operating system file access permissions for the merged plugin-cfg.xml file. These file access permissions allow the HTTP server plug-in process to read the file.

    When you complete this process, we have one plug-in configuration file for multiple stand-alone application server profiles.


    Configure simple load balancing across multiple application server profiles with an administrative agent

    Simple load balancing distributes HTTP requests across multiple IBM WebSphere Application Server instances. Also, we can configure simple load balancing to provide failover of an application state that is maintained in an HTTP session.

    This offering applies to stand-alone application server profiles for IBM WAS. This offering does not include a centralized management capability such as the deployment manager in WAS, Network Deployment. We can configure simple load balancing capability with WAS by combining plugin-cfg.xmls of multiple stand-alone application server profiles into a single configuration file. The number of configuration files that we can combine are bound by the limits that exist in the WAS license agreement. We can use the following different configurations of the application server to combine plugin-cfg.xmls of multiple application server profiles into a single output file:

    • Using multiple stand-alone base application server profiles. For more information, see the documentation on configuring simple load balancing across multiple application server profiles.

    • Using multiple stand-alone base application server profiles with an administrative agent. This topic explains how to complete this configuration.

    • Using multiple stand-alone base application server profiles with an administrative agent using the job manager. The job manager function is a part of WAS, Network Deployment. However, we can use the job manager function with stand-alone, base application server profiles. For more information, see the documentation on configuring simple load balancing across multiple stand-alone, base application server profiles with an administrative agent using the job manager.

    To register stand-alone application server profiles with an administrative agent and combine plugin-cfg.xmls from these profiles into a single output file.

    1. Install WAS and create application server profiles. For more information, see the documentation on WAS installation and application server profiles.

    2. Configure the administrative agent and register each application server profile with the administrative agent. Complete the following steps:

      1. Set up the administrative agent, which includes creating the administrative agent profile.
      2. Register the stand-alone application server with the administrative agent.
      3. Start and stop the administrative agent.

      After completing these steps, we can complete all the administrative operations through the administrative agent. When you log in to the dmgr console for the administrative agent, we can select which application servers to manage. For more information, see the documentation on administering stand-alone nodes using the administrative agent.

    3. Install the enterprise application or web module. For more information, see the documentation on installing enterprise applications or modules.

    4. Determine if you require session affinity.

      Session affinity directs requests from a given client to a specific application server. The application state maintained in the HTTP session is accessed in the HTTP session cache, which is local to the application server. Session affinity provides higher performance than database persistence of the session object, alone. Without session affinity, session requests must be obtained from the database if they are sent to a server that does not have the session object in the local cache.

    5. Optional: Configure a unique HTTP session clone ID for each application server. Complete this step if you require session affinity.

      We can configure a unique HTTP session clone ID using wsadmin scripting or the dmgr console. To use wsadmin commands for the Jython or Jacl programming language, see the documentation on configuring a unique HTTP session clone ID for each application server using scripting. To configure a unique HTTP session clone ID using the dmgr console, complete the following steps:

      1. Expand Servers > Server Types and click WebSphere application servers > server_name.

      2. Under Container Settings, expand Web Container Settings, and click Web container.

      3. Under Additional Properties, click Custom properties > New.

      4. In the Name field, enter HttpSessionCloneId.

      5. In the Value field, enter a unique value for the server. The unique value must be 8 - 9 alphanumeric characters; for example, test1234

      6. Click Apply or OK.

      7. Click Save to save the configuration changes to the master configuration.

    6. Optional: Configure session persistence. If we require session failover capability, configure session persistence. Persistence of the session object to a database is the only option for session failover with WAS. To configure session persistence using the dmgr console, see the documentation on configuring database session persistence. To configure database session persistence using wsadmin commands for the Jython or Jacl programming language, see the documentation on configuring database session persistence using scripting.

    7. Restart the server.

    8. Generate plugin-cfg.xml for each stand-alone application server using the GenPluginCfg script, the dmgr console, or wsadmin scripting.

      To use the GenPluginCfg script, enter the following command on the command line:profile_root/config/cells/GenPluginCfg.sh|bat

      To use the dmgr console, see the documentation on creating or updating a global web server plug-in configuration file.

      The following variables apply to the Jython and Jacl commands:

      • cell_name is the name of the cell.
      • web_server_node is the name of the node for the web server.
      • web_server_name is the name of the web server.

      Jython

      On the command line, enter each of the following commands on a separate line:
      generator = AdminControl.completeObjectName('type=PluginCfgGenerator,*')
      AdminControl.invoke(generator, 'generate', "profile_root/config cell_name web_server_node web_server_name true true")

      Jacl

      On the command line, enter each of the following commands on a separate line:
      set generator [$AdminControl completeObjectName type=PluginCfgGenerator,*]
      $AdminControl invoke $generator generate "profile_root/config cell_name web_server_node web_server_name true true"

    9. Merge plugin-cfg.xmls from multiple application server nodes.

      We can either manually merge plugin-cfg.xmls or use the pluginCfgMerge tool to automatically merge plugin-cfg.xml from multiple application server profiles into a single output file. The pluginCfgMerge.bat or pluginCfgMerge.sh tool is available after you install this fix pack and is located in the install_root/bin directory. To use the pluginCfgMerge tool...

      1. Rename plugin-cfg.xmls to a unique name across the application server profiles.

      2. Copy plugin-cfg.xml for all stand-alone application server profiles into a common directory.

      3. Use the pluginCfgMerge tool to combine plugin-cfg.xmls from each of the application server profiles into a single output file. For example:

          install_root/bin/pluginCfgMerge.sh plugin_configuration_file1 plugin_configuration_file2 resulting_plugin_configuration_file

          install_root\bin\pluginCfgMerge.bat plugin_configuration_file1 plugin_configuration_file2 resulting_plugin_configuration_file

        The resulting_plugin_configuration_file variable value is normally plugin-cfg.xml

      For more information about manually merging plugin-cfg.xmls, see the technote on merging plugin-cfg.xml files from multiple application server profiles.

    10. Copy the merged plugin-cfg.xml file to the plugin_installation_root/config/web_server_name/ directory on the Web server host.

      Ensure that we have defined the correct operating system file access permissions for the merged plugin-cfg.xml file. These file access permissions allow the HTTP server plug-in process to read the file.

    When you complete this process, we have one plug-in configuration file for multiple stand-alone application server profiles.


    Configure load balancing across multiple appserver profiles with an administrative agent

    Simple load balancing distributes HTTP requests across multiple IBM WebSphere Application Server instances. We can configure simple load balancing to provide failover of an application state that is maintained in an HTTP session. We can configure simple load balancing capability with WAS by combining plugin-cfg.xmls of multiple stand-alone application server profiles into a single configuration file. The number of configuration files that we can combine are bound by the limits that exist in the WAS license agreement. We can use the following different configurations of the application server to combine plugin-cfg.xmls of multiple application server profiles into a single output file:

    • Using multiple stand-alone base application server profiles. For more information, see the documentation on configuring simple load balancing across multiple application server profiles.

    • Using multiple stand-alone base application server profiles with an administrative agent. For more information, see the documentation on configuring simple load balancing across multiple application server profiles with an administrative agent

    • Using multiple stand-alone base application server profiles with an administrative agent using the job manager. The job manager function is a part of WAS, Network Deployment. However, we can use the job manager function with stand-alone, base application server profiles. Use this topic to complete this configuration.

    To register stand-alone application server profiles with an administrative agent using a job manager and combine plugin-cfg.xmls from these profiles into a single output file.

    1. Install WAS and create application server profiles. For more information, see the documentation on WAS installation and application server profiles.

    2. Configure the administrative agent and register each application server profile with the administrative agent. Complete the following steps:

      1. Set up the administrative agent, which includes creating the administrative agent profile.
      2. Register the stand-alone application server with the administrative agent.
      3. Start and stop the administrative agent.

      After completing these steps, we can complete all the administrative operations through the administrative agent. When you log in to the dmgr console for the administrative agent, we can select which application servers to manage. For more information, see the documentation on administering stand-alone nodes using the administrative agent.

    3. Install WAS, Network Deployment for the licensed WAS, Network Deployment instances that will perform centralized management for the stand-alone application server instances. For more information, see the installation documentation for the WAS, Network Deployment product.

      You must access the Information Center for WAS, Network Deployment to read its installation documentation.

    4. Create the job manager profile, configure the job manager, and register stand-alone application servers with the job manager. For more information, see the documentation on setting up a job manager environment. We can complete administrative options centrally using the job manager. For more information about the job manager, see the conceptual information about the job manager.

    5. Install the enterprise application or web module. We can use one of the following methods to install the enterprise application or web module:

      • Install the enterprise application or web module on each application server. For more information, see the documentation on installing enterprise applications or modules.
      • Install the enterprise application or web module using the job manager. For more information, see the documentation on installing applications using the job manager.

    6. Determine if you require session affinity.

      Session affinity directs requests from a given client to a specific application server. The application state maintained in the HTTP session is accessed in the HTTP session cache, which is local to the application server. Session affinity provides higher performance than database persistence of the session object, alone. Without session affinity, session requests must be obtained from the database if they are sent to a server that does not have the session object in the local cache.

    7. Optional: Configure a unique HTTP session clone ID for each application server. Complete this step if you require session affinity.

      We can configure a unique HTTP session clone ID using wsadmin scripting or the dmgr console. To use wsadmin commands for the Jython or Jacl programming language, see the documentation on configuring a unique HTTP session clone ID for each application server using scripting. To configure a unique HTTP session clone ID using the dmgr console, complete the following steps:

      1. Expand Servers > Server Types and click WebSphere application servers > server_name.

      2. Under Container Settings, expand Web Container Settings and click Web container.

      3. Under Additional Properties, click Custom properties > New.

      4. In the Name field, enter HttpSessionCloneId.

      5. In the Value field, enter a unique value for each server. The unique value must be 8 - 9 alphanumeric characters; for example, test1234

      6. Click Apply or OK.

      7. Click Save to save the configuration changes to the master configuration.

    8. Optional: Configure session persistence. If we require session failover capability, configure session persistence. Persistence of the session object to a database is the only option for session failover with WAS. To configure session persistence using the dmgr console, see the documentation on configuring database session persistence. To configure database session persistence using wsadmin commands for the Jython or Jacl programming language, see the documentation on configuring database session persistence using scripting.

    9. Restart the server.

    10. Generate plugin-cfg.xml for each stand-alone application server using the GenPluginCfg script, the dmgr console, or wsadmin scripting.

        profile_root/config/cells/GenPluginCfg.sh

      To use the dmgr console, see the documentation on creating or updating a global web server plug-in configuration file.

      The following variables apply to the Jython and Jacl commands:

      • cell_name is the name of the cell.
      • web_server_node is the name of the node for the web server.
      • web_server_name is the name of the web server.

      Jython

      On the command line, enter each of the following commands on a separate line:
      generator = AdminControl.completeObjectName('type=PluginCfgGenerator,*')
      AdminControl.invoke(generator, 'generate', "profile_root/config cell_name web_server_node web_server_name true true")

      Jacl

      On the command line, enter each of the following commands on a separate line:
      set generator [$AdminControl completeObjectName type=PluginCfgGenerator,*]
      $AdminControl invoke $generator generate "profile_root/config cell_name web_server_node web_server_name true true"

    11. Merge plugin-cfg.xmls from multiple application server nodes.

      We can either manually merge plugin-cfg.xmls or use the tool to automatically merge plugin-cfg.xml from multiple application server profiles into a single output file. The .bat or .sh tool is available after you install this fix pack and is located in the install_root/bin directory. To use the tool...

      1. Rename plugin-cfg.xmls to a unique name across the application server profiles.

      2. Copy plugin-cfg.xml for all stand-alone application server profiles into a common directory.

      3. Use the tool to combine plugin-cfg.xmls from each of the application server profiles into a single output file. For example:

          install_root/bin/.sh plugin_configuration_file1 plugin_configuration_file2 resulting_plugin_configuration_file

          install_root\bin\.bat plugin_configuration_file1 plugin_configuration_file2 resulting_plugin_configuration_file

        The resulting_plugin_configuration_file variable value is normally plugin-cfg.xml

      For more information about manually merging plugin-cfg.xmls, see the technote on merging plugin-cfg.xml files from multiple application server profiles.

    12. Copy the merged plugin-cfg.xml file to the plugin_installation_root/config/web_server_name/ directory on the Web server host.

      Ensure that we have defined the correct operating system file access permissions for the merged plugin-cfg.xml file. These file access permissions allow the HTTP server plug-in process to read the file.

    When you complete this process, we have one plug-in configuration file for multiple stand-alone application server profiles.


    Transport chains

    Transport chains represent a network protocol stack used for I/O operations within an application server environment.

    Transport chains are part of the channel framework function that provides a common networking service for all components.

    A transport chain consists of one or more types of channels, each of which supports a different type of I/O protocol, such as TCP, DCS. or HTTP. Network ports can be shared among all of the channels within a chain. The channel framework function automatically distributes a request arriving on that port to the correct I/O protocol channel for processing.

    The transport chain configuration settings determine which I/O protocols are supported for that chain. Following are some of the more common types of channels. Custom channels that support requirements unique to a particular customer or environment can also be added to a transport chain.

    HTTP inbound channel

    Used to enable communication with remote servers. It implements the HTTP 1.0 and 1.1 standards and is used by other channels, such as the web container channel, to serve HTTP requests and to send HTTP specific information to servlets expecting this type of information.

    HTTP inbound channels are used instead of HTTP transports to establish the request queue between a web server plug-in, and a web container in which the web modules of an application reside.

    HTTP proxy inbound channel

    Used to handle HTTP requests between a proxy server and application server nodes.

    HTTP Tunnel channel

    Used to provide client applications with persistent HTTP connections to remote hosts that are either blocked by firewalls or require an HTTP proxy server, including authentication, or both. An HTTP Tunnel channel enables the exchange of application data in the body of an HTTP request or response sent to or received from a remote server. An HTTP Tunnel channel also enables client-side applications to poll the remote host and to use HTTP requests to either send data from the client or to receive data from an application server. In either case, neither the client nor the application server is aware that HTTP is being used to exchange the data.

    JFAP channel

    Used by the JMS server to create connections to JMS resources on a service integration bus.

    MQ channel

    Used in combination with other channels, such as a TCP channel, within the confines of WebSphere MQ support to facilitate communications between a service integration bus and a WebSphere MQ client or queue manager.

    SIP channel

    Used to create a bridge in the transport chain between a session initiation protocol (SIP) inbound channel, and a servlet and JavaServer Page engine.

    SIP container inbound channel

    Used to handle communication between the SIP inbound channel and the SIP servlet container.

    SIP inbound channel

    Used to handle inbound SIP requests from a remote client.

    SSL channel

    Used to associate an SSL configuration repertoire with the transport chain. This channel is only available when SSL support is enabled for the transport chain. An SSL configuration repertoire is defined in the dmgr console, under security, on the SSL configuration repertoires > SSL configuration repertoires page.

    TCP channel

    Used to provide client applications with persistent connections within a Local Area Network (LAN) when a node uses transmission control protocol (TCP) to retrieve information from a network.

    UDP channel

    Used to provide client applications with persistent connections within a Local Area Network (LAN) when a node uses user datagram protocol (UDP) to retrieve information from a network.

    Web container channel

    Used to create a bridge in the transport chain between an HTTP inbound channel and a servlet and JavaServer Page (JSP) engine.


    Configure the web server plug-in for Secure Sockets Layer

    WebSphere Application Server has an internal HTTP transport that accepts HTTP requests. If we install an external HTTP server, the web server plug-in must forward requests from the external HTTP server to Application Server internal HTTP transport. Follow instructions provided by the HTTP vendor to install and configure the HTTP server. Test the HTTP server by accessing http://your-host-URL and https://your-host-URL. You should also have a web server plug-in installed. x64.

    1. Create a directory on the web server host for storing the key ring file referenced by the plug-in and associated files, for example: plugin_install_root/etc/keys.

    2. From the dmgr console, click Servers > Web servers.

    3. Select the web server name.

    4. Click Plug-in properties.

    5. Click Manage keys and certificates to access configuration options for the keys and certificates. By default, we can change the password used to protect the key store.

    6. Click OK.

    7. Click Copy to web server keystore directory to copy the keystore and to stash files to a managed web server. For non-managed web servers, use FTP to copy them.

      You must copy the keystore file to the web server for the web server to function properly.

    8. Optional: Under Additional Properties, we can also select one of the following:

      • Signer certificates - Use to add new certificates, delete certificates, extract certificates, and to retrieve certificates from a port.

      • Personal certificates - Use to create a new chained or self-signed certificate, delete a certificate, or to import and export a personal certificate.

      • Personal certificate requests - Use to manage personal certificate requests.

      • Custom properties - Use to define custom properties for the key store.

    The IBM HTTP Server plug-in and the internal Web server are configured for SSL.


    Key store settings

    To create all keystore types, including cryptographic, Resource Access Control Facility (RACF), Certificate Management Services (CMS), Java, and all truststore types...

    Links to Personal certificates, Signer certificates, and Personal certificate requests enable you to manage certificates in a manner similar to iKeyman capabilities. A keystore can be file-based, such as CMS or Java keystore types, or it can be remotely managed.

    Any changes made to this panel are permanent.

    Settings include...

    Name Unique name to identify the keystore. The keystore is typically scoped by the ManagementScope scopeName based on the location of the keystore. The name must be unique within the existing keystore collection. Description of the keystore.
    Management scope Scope where this SSL configuration is visible. For example, if you choose a specific node, then the configuration is only visible on that node and any servers that are part of that node.
    Path Location of the keystore file in the format needed by the keystore type. This file can be a dynamic link library (DLL) for cryptographic devices or a filename or file URL for file-based keystores. It can be a safkeyring URL for RACF keyrings.
    Control region user Specifies the Control region Started Task user ID in which the Control region System Authorization Facility (SAF) keyring is created. The user ID must match the exact ID being used by the Control region. Note: This option only applies when creating writable SAF keyrings on z/OS .
    Servant region user Servant region Started Task user ID in which the Servant region System Authorization Facility (SAF) keyring is created. The user ID must match the exact ID being used by the Servant region. Note: This option only applies when creating writable SAF keyrings on z/OS.
    Password [new keystore] | Password [existing keystore] Password used to protect the physical keystore in the operating system. For the default keystore (names ending in DefaultKeyStore or DefaultTrustStore), the password is WebAS. This default password must be changed. This field can be edited. To push the key store to all nodes, the path should be:

      ${CONFIG_ROOT}/cells/CELLNAME/yourkeystore.kdb
    Confirm password Confirmation of the password to open the keystore file or device.
    Type Implementation for keystore management based on java.security. Defines the tool that operates on this keystore type. The list of options is returned by...

      java.security.Security.getAlgorithms("KeyStore")

    Default: PKCS12

    Read only Whether the keystore can be written to or not. If the keystore cannot be written to, certain operations cannot be performed, such as creating or importing certificates.
    Remotely managed Whether the key store is remotely managed, which means that a remote MBean call is needed to update the key store based on the host name specified in the host list field. Most hardware cryptographic token devices are remotely managed. If a key store is marked remotely managed, list the host name of the server where the device is installed in the Host list field.
    Initialize at startup Whether the keystore needs to be initialized before it can be used for cryptographic operations. If enabled, the keystore is initialized at server startup.
    Enable cryptographic operations on hardware device Whether a hardware cryptographic device is used for cryptographic operations only. Operations that require a login are not supported when using this option.


    Configure transport chains

    A transport chain consists of one or more types of channels, each of which supports a different type of I/O protocol, such as TCP or HTTP. Network ports can be shared among all of the channels within a chain. The channel framework function automatically distributes a request arriving on that port to the correct I/O protocol channel for processing.

    Ensure that a port is available for the new transport chain. If we need to set up a shared port, you must:

    • Use wsadmin commands to create the transport chain.
    • Make sure that all channels sharing that port have the same discrimination weight assigned to them.

    You need to configure transport chains to provide a common networking service for all components.

    We can use either the dmgr console or wsadmin commands to create a transport chain. If we use the dmgr console...

    1. In the dmgr console, click...

        Servers | Server Types | WebSphere application servers | server_name | Container

      ...or...

        Servers | Server Types | WebSphere proxy servers | server_name | Container

      ...and then select one of the following

      • SIP Container Settings | SIP container transport chains
      • Web container settings | Web container transport chains
      • Server [ Messaging engine inbound transports |WebSphere MQ link inbound transports ]

      For proxy servers, under HTTP proxy server settings, click...

        Proxy server transports [ HTTPS_PROXY_CHAIN | HTTP_PROXY_CHAIN ] | HTTP proxy inbound channel | New

      The Create New Transport Chain wizard initializes. During the transport chain creation process, you are asked to:

      • Specify a name for the new chain.

      • Select a transport chain template

      • Select a port, if one is available to which the new transport chain is bound. If a port is not available or to define a new port, specify a port name, the host name or IP address for that port, and a valid port number.

        If we are configuring a chain containing a TCP channel, the wizard displays a list of configured TCP channels and a list of the ports the listed TCP channels are not using. Select one of the ports that none of the other TCP channels are using.

        Similarly, if you are configuring a transport chain containing a UDP channel, the wizard displays a list of already configured UDP channels and a list of the ports these UDP channels are not using. Select one of the ports that none of the other UDP channels are using.

      When you click Finish, the new transport chain is added to the list of defined transport chains on the Transport chain panel.

    2. Click the name of a transport chain to view the configuration settings that are in effect for the transport channels contained in that chain.

      To change any of these settings...

      1. Click the name of the channel whose settings you need to change.

      2. Change the configuration settings.

        Some of the settings, such as the port number, are determined by what is specified for the transport chain when it is created and cannot be changed.

      3. Click on Custom properties to set any custom properties that are defined for the system.

    3. When you the configuration changes, click OK.

    4. Stop the application server and start it again.

      Stop the application server and start it again before the changes take effect.

    Update any routines we have that issue a call to start transports during server startup. When a routine issues a call to start transports during server startup, the product converts the call to a transport channel call.

    If we create a new web container transport chain, the initial value for the writeBufferSize attribute is 8192, which is too small for most web container transport chains. It is recommended that we use the dmgr console or wsadmin scripting to change the value of this attribute to 32768. Complete the following steps to use the dmgr console, to change the value of this attribute:

    1. Click Servers and expand Server Types.

    2. Click WebSphere application servers > server_name.

    3. Expand Web Container Settings and click Web container transport settings > transport_chain_name.

    4. Click Web container inbound channel.

    5. Specify 32768 in the Write buffer size field, and click OK.

    6. Click Save.

    To change the value using wsadmin.sh, see the documentation about working with Web container inbound channel properties files.


    Change the HTTP plug-in configuration

    We can change the HTTP plug-in configuration without having to stop the server and start it again. Restriction: The hot deployment and dynamic reloading function is not supported when the product is running on these operating systems. The JAR files within the associated Java Development Kit (JDK) are memory mapped. If these JAR files are updated by the hot deployment and dynamic reloading functionality when they are being used by the Java virtual machine (JVM), the files become inconsistent, which results in an application server crash. When you make changes to an application on these operating systems, do not use the hot deployment and dynamic reloading functionality. Instead, restart the application to reflect the changes.

    There are several change that we can make to the HTTP plug-in configuration without stopping the server and starting it again.

    See Ways to update enterprise application files and determine whether hot deployment is the appropriate way for you to update the HTTP plug-in configuration. Other ways are easier and hot deployment is appropriate only for experienced users.

    The following table lists the changes that we can make to the HTTP plug-in configuration. The table also states whether we use hot deployment or dynamic reloading to make the changes.

    Change Hot deployment Dynamic reloading
    Change application.xml to change the context root of a web application archive (WAR file). Yes No
    Change the web.xml file to add, remove, or modify a servlet mapping. Yes Yes
    Change server.xml to add, remove, or modify an HTTP transport or change the virtualhost.xml file to add or remove a virtual host or to add, remove, or modify a virtual host alias. Yes Yes

    To persist changes, before running GenPluginCfg.sh, delete...

      profile_root/config/cells/plugin-cfg.xml

    • Change application.xml to change the context root of a WAR file.

      1. Change application.xml.

      2. If the plug-in configuration property Automatically propagate plug-in configuration file is selected for this plug-in, it is automatically regenerated whenever application.xml changes.

        We can also run the GenPluginCfg.bat/sh script, or issue a wsadmin command to regenerate plugin-cfg.xml.

    • Change the web.xml file to add, remove, or modify a servlet mapping.

      1. Change the web.xml file.

      2. If the plug-in configuration property Automatically propagate plug-in configuration file is selected for this plug-in, it is automatically regenerated whenever the web.xml file changes.

        If the web application has file serving enabled or has a servlet mapping of /, the plug-in configuration does not have to be regenerated. In all other cases a regeneration is required.

    • Change server.xml to add, remove, or modify an HTTP transport or change the virtualhost.xml file to add or remove a virtual host or to add, remove, or modify a virtual host alias.

      1. Change server.xml or the virtualhost.xml file.

      2. If the plug-in configuration property Automatically propagate plug-in configuration file is selected for this plug-in, it is automatically regenerated whenever server.xml changes.


    Tune web servers

    WebSphere Application Server provides plug-ins for several web server brands and versions. Each web server operating system combination has specific tuning parameters that affect the application performance. Following is a list of tuning parameters specific to web servers. The listed parameters may not apply to all of the supported web servers. Check the web server documentation before using any of these parameters.

    • Tune the IBM HTTP Server 2.0.47.1, Apache 2.0.48, IHS 6.0, and IHS 6.1.
      Monitoring the CPU utilization and checking the IHS error_log and http_plugin.log files can help you diagnose web server performance problems.

      We can also configure the IHS to show a status page:

      • Edit the IHS httpd.conf file and remove the comment character (#) from the following lines in this file:
        #LoadModule status_module, modules/ApacheModuleStatus.dll,
        #<Location/server-status>     #SetHandler server-status
        #</Location>

      • Save the changes and restart the IHS.

      • In a web browser, go to: http://your_host/server-status. Alternatively, click Reload to update status.

      • Optional. If the browser supports refresh, go to http://your_host/server-status?refresh=5 to refresh every five seconds.

      All of these web servers allocate a thread to handle each client connection. Ensuring that enough threads are available for the maximum number of concurrent client connections helps prevent this tier from being a bottleneck. The settings for these web servers can be tuned by making changes to httpd.conf on the web server system.

      We can check the IHS error_log file to see if there are any warnings about having reached the maximum number of clients (MaxClients). There are several parameters, depending on the specific operating system platform, that determine the maximum number of clients the web server supports.

    • Support thousands of concurrent clients.
      It is not unusual for a single IHS system to support thousands of concurrent clients. If the requirements are to support more concurrent clients than the number of threads that are supported by the web server operating system and hardware, consider using multiple web servers.

    • Respond to a Connection Refused error message. Some clients might receive a Connection Refused error message if there is a sudden increase in the number of clients. Increasing the ListenBacklog and StartServer parameters can reduce or eliminate this error.

      • The ListenBacklog parameter indicates to the operating system the maximum allowed number of pending connections. Although the IHS default is 511, the actual value can be much higher or lower depending on the corresponding operating system parameter. To handle large numbers of simultaneous connections, this parameter and the corresponding OS parameter might need to be set to the number (possibly thousands) of expected simultaneous connections.

      • The StartServers parameter indicates the number of IHS processes to initially start. Pre-starting these IHS threads/processes reduces the chance of a user having to wait for a new process to start. You should set this parameter to a value equal to the MinSpareServers parameter so the minimum number of IHS processes needed for this client load is started immediately.

    • Prevent the frequent creation and destruction of client threads/processes as the number of users change.
      We can a use the MinSpareServers and MaxSpareServers to specify the minimum and maximum number of servers (client threads/processes) that can exist in an idle state. To prevent frequent creation and destruction of client threads/processes as the number of users change, set this range large enough to include the maximum number of simultaneous users.

    • Change the setting on the web server's Access logging parameter to reduce the load on the web server.
      If we do not need to log every access to the appserver, change the default value of the web server's Access logging parameter. This change will reduce the load on the web server.

    • Modify the settings of the Load balancing option and Retry interval web server plug-in properties to improve performance.
      We can improve the performance of IHS (with the WebSphere web server plug-in) by modifying the following web server plug-in configuration properties:

      • Load balancing option, which specifies the load balancing option the plug-in uses in sending requests to the various application servers associated with that web server.

        The goal of the default load balance option, Round Robin, is to provide an even distribution of work across cluster members. Round Robin works best with web servers that have a single process sending requests to the appserver. If the web server is using multiple processes to send requests to the appserver, the Random option can sometimes yield a more even distribution of work across the cluster.

      • Retry interval value, which specifies the length of time to wait before trying to connect to a server that has been marked temporarily unavailable.

        How can lowering the retry interval affect throughput ? If the plug-in attempts to connect to a particular application server and that application server is offline or in the process of restarting, the requests must wait for a timeout period. This process causes delayed responses for those requests. If we set the retry interval value too high, then an available application server is not utilized.

        Specify the retry interval value based on the following factors:

        • How long it will take for the application servers to restart
        • How averse you are to the delay caused by retrying too often
        • How important it is to utilize all of the application servers

      Making these changes can help the IHS to support more product users. To modify these properties, in the dmgr console, click...

        Servers | Server Types | Web Servers | web_server_name | Plug-in properties | Request routing


    GenPluginCfg command

    Regenerate the web server plug-in configuration file, plugin-cfg.xml.

    For more information about where to run this command, see the Use command tools article.

    Regenerating the plug-in configuration can overwrite manual configuration changes that you might want to preserve. Before performing this task, understand its implications as described in Implement a web server plug-in.

    You must delete plugin-cfg.xml in the profile_root/config/cells directory before we use this command. Otherwise, configuration changes do not persist to plugin-cfg.xml.

    To regenerate the plug-in configuration perform one of the following:

    • Click on Servers > Server Types > Web servers in the dmgr console, select a web server and then click Generate Plug-in.

    • Run...

    Both methods for regenerating the plug-in configuration create a plugin-cfg.xml file in ASCII format, which is the proper format for execution in a distributed environment.

    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.

    When the GenPluginCfg command is issued with the option -webserver.name webservrName, wsadmin generates plugin-cfg.xml for the web server. The settings in the generated configuration file are based on the list of applications deployed on the web server. When this command is issued without the option -webserver.name webservrName, plugin-cfg.xml is generated based on topology.

    The following options are available for the GenPluginCfg command:

    -config.root configroot_dir

    Defaults to CONFIG_ROOT. The setupCmdLine command is invoked to get this environment variable.

    -profileName

    Defines the profile of the appserver 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.

    -cell.name cell

    Defaults to WAS_CELL. The setupCmdLine command is invoked to get this environment variable.

    -node.name node

    Defaults to WAS_NODE. The setupCmdLine command is invoked to get this environment variable.

    -webserver.name webserver1

    Required for creating plug-in configuration file for a given Web server.

    -propagate yes/no

    Applicable only when the webserver.name option is specified and the web server is local. Otherwise, manually copy the plugin-cfg.xml file from app_server_root/profiles/profile_name/config/cells/cell_name/nodes/node_name/servers/web_server_name to plugins_root/config/web_server_name in the remote web server plugins directory. Default is no.

    -propagateKeyring yes/no

    Applicable only when the option webserver.name is specified and the web server is local. Defaults to no.

    -cluster.name cluster1,cluster2 | ALL

    Optional list of clusters. Ignored when the option webserver.name is specified.

    -server.name server1,server2

    Optional list of servers. Required for single server plug-in generation. Ignored when the option webserver.name is specified.

    -output.file.name file_name

    Defaults to the configroot_dir/plugin-cfg.xml file. Ignored when the option webserver.name is specified.

    -destination.root root

    Installation root of the machine configuration is used on. Ignored when the option webserver.name is specified.

    -destination.operating.system windows/unix

    Operating system of the machine configuration is used on. Ignored when the option webserver.name is specified.

    -force yes

    Creates a new configuration instead of attempting to merge with an exiting configuration when command is issued for a cell-wide file generation.

    -debug yes/no

    Defaults to no.

    -help

    Prints a usage statement.

    -?

    Prints a usage statement.

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

      GenPluginCfg -cell.name NetworkDeploymentCell

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

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

    To generate plugin-cfg.xml for a web server:

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


    Allow web servers to access the dmgr console

    Set the admin_host virtual host group to include the web server port (80 by default) by going to...

      Environment | Virtual Host | admin_host | Host Aliases | New

    ...and setting...

      webhost.myco.com:port

    Stop and restart the application server.

    Edit plugin-cfg.xml to include the following entries:

        <VirtualHostGroup Name="admin_host">         < VirtualHost Name="*:9060"/>         <VirtualHost Name="*:80"/>         <VirtualHost Name="*:9043"/>     </VirtualHostGroup> 
        ...
        ...
        ...
    
        <ServerCluster Name="server1_SERVER1HOSTserver1_Cluster"> 
            <Server LoadBalanceWeight="1" 
                Name="SERVER1HOSTserver1_dmgr"> 
                <Transport Hostname="SERVER1HOST" 
                              Port="9060" 
                              Protocol="http"/> 
            </Server>         
            <PrimaryServers>             <Server Name="SERVER1HOSTserver1_dmgr"/>         </PrimaryServers> 
        </ServerCluster> 
        ...
        ...
        ...
    
        <UriGroup Name="admin_host_server1_SERVER1HOSTserver1_Cluster_URIs"> 
            <Uri AffinityCookie="JSESSIONID"
                 AffinityURLIdentifier="jsessionid" 
                 Name="/ibm/console/*"/> 
        </UriGroup> 
        <Route ServerCluster="server1_SERVER1HOSTserver1_Cluster"
                  UriGroup="admin_host_server1_SERVER1HOSTserver1_Cluster_URIs" 
                  VirtualHostGroup="admin_host"/>


    Remote user information

    If an application calls the getRemoteUser method, it relies on a private HTTP header containing remote user information that is parsed by the plug-in. The plug-in sets the private HTTP header value whenever a web server authentication module populates the remote user in the web server data structure. If the private HTTP header value is not set, the call to getRemoteUser method by the application returns a null value.

    Web server Private header built from...
    Apache Request record.
    IHS Request record.
    Sun One The auth_user property associated with the request. Name of local HTTP user of the web browser, if HTTP access authorization is activated for the URL.
    Domino The REMOTE_USER environment variable. Anonymous for users who have not logged in. Username for users who are logged in.
    IIS The REMOTE_USER environment variable. Set to name of the user as derived from the authorization header sent by the client.

    If the private header is not being set in the Sun One, IIS, or Domino Web Server plug-in, make sure the request record includes information about the user requesting the data.

    If an call to getRemoteUser method by the application returns a null value, or if the correct remote user information is not being added to the data structure for the web server plug-in, make sure the remote user parameter within the vendor-acquired authentication module is still set to YES. (Sometimes this parameter gets set to NO when service is applied.)


    Run multiple web server child processes

    We can configure most web servers to start multiple child processes. In this situation, each child process loads its own instance of the web server. When running multiple web server child processes, remember that:

    • Multiple running instances of the web server plug-in cannot share information. Therefore the dynamically changing load balance weight of each application server is not shared between the web server plug-in instances. For example, one instance of the web server plug-in might consider an application server to be running with a weight of 5, while another instance of the web server plug-in might be consider the same application server to be down and unusable. This difference in perspective might cause an incoming request to be handled differently, depending on which web server plug-in instance handles the request.

    • The web server plug-in settings are handled on a per instance basis. For example, the MaxConnections property specifies the number of pending requests allowed on that web server, for each web server plug-in instance. If the MaxConnections property is set to 20, and you start three web server child processes, each of the three web server plug-in instances allow 20 pending connections to the same application server, which means there could be up to 60 pending connections.


    Create or update a global web server plug-in configuration file

    If all of the application servers in a cell use the same web server to route requests for dynamic content, such as servlets and portlets.to application servers, we can create a global web server plug-in configuration file for that cell. The resulting plugin-cfg.xml file is located in the profile_root/config/cells directory. You must update the global web server plug-in configuration file whenever you change the configuration settings for an application server, cluster, virtual host, or web container transport that is part of that cell, or when add a new application server, cluster, virtual host, or web container transport to that cell.

    To update the configuration settings for a global web server plug-in, we can either use the Update global web server plug-in configuration page in the dmgr console, or issue the following command:

      %was_profile_home%/config/cells/GenPluginCfg.sh|bat

    Both methods for regenerating the global web server plug-in configuration create a plugin-cfg.xml file in ASCII format.

    To use the Update global web server plug-in configuration page in the dmgr console:

    1. Click Environment > Update global web server plug-in configuration.

    2. Click OK to update plugin-cfg.xml.

    3. To view or download the current version of this file, click...

        View or download the current web server plug-in configuration file

      We can select this option to:

      • View the current version of the file before you update it.
      • View the file after it is updated.
      • Download a copy of this file to a remote machine.

    Regenerating the configuration 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. Whether triggered manually or occurring automatically, plug-in regeneration requires about 30 to 60 seconds to complete when the application server is on the same physical machine (node) as the web server. In other cases, it takes more time.

    The delay is important because it determines how soon the new plug-in configuration takes effect. Suppose you add a new served path for a servlet, then regenerate the plug-in configurations. The regeneration requires 40 seconds, after which a user should be able to access the servlet by the new served path.

    For an HTTP plug-in, the length of the delay is determined by the Refresh Interval attribute of the Config element in plugin-cfg.xml. The plug-in polls the disk, or file system, at this interval to see whether the configuration has changed. The default interval is 60 seconds. To regenerate the plug-in configuration requires twice the refresh interval.

    In a development environment in which we are frequently changing settings in the dmgr console, IBM recommends set the refresh interval to 3 to 5 seconds.

    In a production environment, set a longer refresh interval, perhaps as long as 30 minutes, depending on the frequency of changes.

    You might need to stop the application servers in the cell and then start the application servers again before the changes to the plug-in configuration go into effect.

    If the web server is running on a remote machine, click View or download the current web server plug-in configuration file to download a copy of plugin-cfg.xml to a that machine.


    Gskit install images files

    The Global Security Kit (GSKit) installation image files for the WebSphere Web server plug-ins are packaged on the CD with the web server plug-in files.

    We can download the appropriate GSKIT file to the workstation on which the web server is running.

    The Global Security Kit (GSKit) installation images files for the WebSphere Web Server Plug-ins are provided as a "local install" and are not installed globally nor are registered with the native package management utilities.


    Web server plug-in tuning tips

    Important tips for web server plug-in tuning include how to balance workload and improve performance in a high stress environment. Balancing workloads among application servers in a network fronted by a web server plug-in helps improve request response time.

    Limiting the number of connections that can be established with an application server works best for web servers that follow use a single, multithreaded process for serving requests.

    IBM HTTP Server uses a single, multithreaded process for serving requests. No configuration changes are required.

    IHS typically uses multiple multithreaded processes for serving requests. Specify the following values for the properties in the web server configuration file (httpd.conf) to prevent the IHS from using more than one process for serving requests.

    ServerLimit           1
    ThreadLimit           1024
    StartServers          1
    MaxClients            1024
    MinSpareThreads       1
    MaxSpareThreads       1024
    ThreadsPerChild       1024
    MaxRequestsPerChild   0


    Improving performance in a high stress environment

    If we use the default settings for a Microsoft Windows operating system, you might encounter web server plug-in performance problems if you are running in a high stress environment. To avoid these problems, consider tuning the TCP/IP setting for this operating system. Two of the keys setting to tune are TcpTimedWaitDelay and MaxUserPort.

    To tune the TcpTimedWaitDelay setting, change the value of the tcp_time_wait_interval parameter from the default value of 240 seconds, to 30 seconds:

    1. Locate in the Windows Registry:

        HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\tcpip\Parameters\TcpTimedWaitDelay
      If this entry does not exist in the Windows Registry, create it by editing this entry as a new DWORD item.

    2. Specify, in seconds, a value between 30 and 300 inclusive for this entry. (It is recommended specified a value of 30. )

    To tune the MaxUserPort setting:

    1. Locate in the Windows Registry:

        HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\tcpip\Parameters\MaxUserPort
      If this entry does not exist in the Windows Registry, create it by editing this entry as a new DWORD item.
    2. Set the maximum number of ports to a value between 5000 and 65534 ports, inclusive. (It is recommended specified a value of 65534,)

    See the Microsoft website for more information about these settings.


    Private headers

    A web server plug-in can use private headers to forward requests for dynamic content, such as servlets, to the application server.

    After you configure a web server plug-in, in addition to regular plug-in functions, we can use private headers as a mechanism for forwarding proxy information from the plug-in to an application server. This information is not normally included in HTTP requests.

    Private headers are implemented as a set of HTTP request header name and value pairs the plug-in adds to the HTTP request header before the request is forwarded to an application server. The application server's web container removes this information from the header and then processes this information.

    Private headers can include such information as the remote (client) user, the remote (client) host name, or an SSL client certificate. They conform to a naming standard so there is no namespace collision with the architected HTTP header fields.

    For example, authentication information, such as a client certificate, is normally requested by the web server once during the establishment of an HTTP session. It is not required again for individual requests within that session. However, a client certificate must accompany each request forwarded to the application server. The application server can then use the certificate as needed.

    Similarly, the web server examines TCP/IP socket connections for information about the host address of the client. The application server cannot perform this examination because its socket connection is with the plug-in and not with the actual client. Therefore, one of the private headers is the host address of the actual client.


    See also


    +

    Search Tips   |   Advanced Search