Replace the certificates

Question

This document describes the steps necessary to replace the certificates in IBM WebSphere Application Server V6.1 when the certificates have expired or if the nodes are out of sync.

Answer

This is meant to be used ONLY for V6.1. Do NOT try to follow these instructions on any newer versions of WebSphere.

NOTE: This document assumes that you are using a default configuration. If you have made modifications to your SSL configurations you will need to take these changes into account. For example, additional steps will be required if you have enabled client authentication on the application servers.

1. Run backupConfig on the Deployment Manager.

2. This step is optional. It only needs to be performed if you are running at level previous to 6.1.0.23 and the nodes are still in sync. You do not need to stop the nodeagent(s) and appserver(s) if you are at or above this level and the nodes are in sync.

Stop all of the nodeagents and application servers in the cell. Stop the Web server(s). Start the Deployment Manager.

3. Replace the Deployment Manager certificate.

i. In the Administrative Console, go to Security > SSL certificate and key management > Key stores and certificates > CellDefaultKeyStore > Personal certificates > Create a self-signed certificate

 

ii. Enter the required attributes.

Alias : cell_default
Common name : <hostname>
Validity period : <number of days> <-- this can be set greater than 365
Organization : <company>

Click OK and Save the changes.

iii. Return to Security > SSL certificate and key management > Key stores and certificates > CellDefaultKeyStore > Personal certificates

iv. Select the old certificate and click Replace.

v. On the next screen, you are able to choose which certificate will replace the old certificate. Accept your new certificate. Do not select either Delete old certificate after replacement or Delete old signers. Accept your new certificate and any browser prompts.

vi. On the next screen, select the old certificate and click Delete. Click OK and Save the changes.

At this point the Deployment Manager has its certificate replaced.

4. Add the Deployment Manager signer certificate to the CellDefaultTruststore.

i. Go to SSL certificate and key management > Key stores and certificates.

ii. Select CellDefaultKeyStore and CellDefaultTrustStore and click Exchange signers.



iii. Select the certificate in CellDefaultKeyStore personal certificates created in previous step and click Add.



Click OK and Save the changes. 

5. Replace the certificate on the node(s).

This step will need to be done for each node in the cell.

i. Go to Security > SSL certificate and key management > Manage endpoint security configurations.

ii. Under Inbound, click the link for the node, node_name (NodeDefaultSSLSettings,null).

iii. Click the Manage certificates button.



iv. Click Create a self-signed certificate.

v. Enter the required attributes.

Alias : nodeX_default <-- where X is the node number
Common name : <hostname>
Validity period : <number of days> <-- this can be set greater than 365
Organization : <company>

Click OK and Save the changes.

vi. Return to Security > SSL certificate and key management > Manage endpoint security configuration s, click node_name (NodeDefaultSSLSettings,null), clickManage certificates.

vii. Select the old certificate and click Replace.

viii. On the next screen, you are able to choose which certificate will replace the old
certificate. Accept your new certificate. Do not select either Delete old certificate after replacement or Delete old signers.

ix. On the next screen, select the old certificate and click Delete. Click OK and save the changes.

6. Add the Node signer certificate to the CellDefaultTruststore.

This step will need to be done for each node in the cell.

i. Go to Security > SSL certificate and key management > Manage endpoint security configurations.

ii. Under Inbound, click the link for the node, node_name (NodeDefaultSSLSettings,null)and select Key stores and certificates.

iii. Select NodeDefaultKeyStore and CellDefaultTrustStore and then Click Exchange signers.

iv. Select the certificate in NodeDefaultKeyStore personal certificates created in previous step and click Add.



Click OK and Save the changes.

7. Repeat steps 5 and 6 for each node in the cell.


8. Delete the old signer certificates and extract the new ones.

i. Go to SSL certificate and key management > Key stores and certificates > CellDefaultTrustStore > Signer certificates

ii. Select all of the old signer certificates and click Delete. If you are not sure, you can compare the Fingerprint and/or the Expiration dates with the personal certificate in the keystores.

iii. Select one of the new certificates. Click Extract.

iv. Enter a File Name that corresponds to the certificate. For example, node1.arm. ClickOk.

v. Repeat iii. and iv. for each of the new certificates making sure you have done this for thecell signer and all of the node signers. These files are saved to the profile_root/Dmgr/ directory.

9. Manually copy the trust store to each of the /etc directories.

i. Backup the trust.p12 in profile_root \Dmgr\etc

ii. Copy the profile_root \Dmgr\config\cells\ cell-name \trust.p12 to profile_root\Dmgr\etc

iii. Backup the trust.p12 on each of the nodes profile_root \Appsrv\etc directories.

iv. Copy the profile_root \Dmgr\config\cells\ cell-name \trust.p12 to profile_root\Appsrv\etc

v. Repeat the previous step for each node in the cell.

10. This step is optional. It only needs to be performed if you are running at a level previous to 6.1.0.23. You do not need to stop the nodeagent(s) and appserver(s) if you are at or above this level.

i. Restart the Deployment Manager.

ii. Run a command line syncNode from each of the nodes.

iii. Start the nodeagents and application servers. They should now be fully synchronized with the new certificates in place. 

11. Propagate the signer certificate(s) to plug-in(s).

i. Go to Servers > Web servers. Click webserver_name, then under Additional Properties click Plug-in properties.

IMPORTANT NOTE : Depending on your configuration you may or may not be able to perform the next 3 steps with the console. If the fields are greyed out and you are unable to manage your plugin-key.kdb from the console you will need to use IKEYMAN to manually add the certificates from step 8. iv. to the Web server plugin-key.kdb file and then continue at step 11 v.

ii. Click Manage keys and certificates under Additional Properties, click Signer certificates and then click Add.


iii. Enter a unique Alias Name and then specify the File Name that you created in step 8. iv.

iv. Repeat this for each of the new certificates making sure you have done this for the cell signer and all of the node signers.

v. Manually copy the plugin-key.kdb from the local configuration to the Web server.

Default local configuration location:
profile_root \Dmgr\config\cells\ cell-name \nodes\ node-name \servers\ web-server-name \plugin-key.kdb

Default Web server location:
Web-server-root \Plugins\config\ web-server-name \plugin-key.kdb

Note: You can also determine the location from the Plug-in properties page in step i.

vi. Repeat steps i. to v. for each Web server if you have more than one.

vii. Start the Web server(s).

SSO

Enabling single sign-on (SSO) on all instances of Websphere Application server for which you plan to enable SSO requires 2 steps to (make SSO work) action.

                a) Enable SSO and Export LTPA Keys.

                b) Enable SSO and Import LTPA Keys.

     To enable SSO on Websphere Application Server:

• Log in to the Websphere Application Server Administration Console.
• Navigate to Security > Global Security.
• Expand the Web and SIP Security.
• Click on Single sign-on(SSO).
• In the General Properties, specify the following configuration parameters for single sign-on: 
• Enabled: selected by default(if not enable it)
• Requires SSL: specifies that single sign-on(SSO) is enabled only when requests are made over HTTPS Secure Sockets Layer(SSL) Connections.
• Interoperability Mode: Select this field if not selected by default.
• Web inbound security attribute propagation: selected by default.
• Click OK and save the changes to master configuration.
• Repeat the same steps for the other instances of Websphere Application Server for which you plan to establish SSO.

Exporting LTPA Keys:

Exporting LTPA key from Websphere Application Server to import into other instances of the Websphere Application Server.  We only need to export the LTPA Key from one server.

      To export the LTPA Keys:

• Log in to the Websphere Application Server Administration Console.
• Navigate to Security > Global Security, click on LTPA.
• In the cross-cell sign-on section, specify a password for the LTPA Key.
• Enter the LTPA Key name and directory to which you want to export the key in the Fully Qualified Key File Name file. For ecample, on unix : /opt/IBM/WebSphere/Keys/Cell01_LTPA_Key_Name.
• Click Export Keys.
• Click OK and save the changes to the master configuration.
• Navigate to the deidrecroty where you exported the LTPA Key.
• Copy the LTPA Key to the file system where we plan to import it.

Importing LTPA Keys:

Import the LTPA Key in to the Websphere Application Server. You can import the same LTPA Key into multiple servers.

•        Enable SSO.
•        Export the LTPA Key.
•        Copy the LTPA Key from the file system where you exported it to the file system where you plan to import it.

To import the LTPA Keys:

•      Log in to the Websphere Application Server Administration Console.
•      Navigate to Security > Global Security, click on LTPA.
•      In the cross-cell sign-on section, specify a password for the LTPA Key.
•      Enter the directory on the file system where we copied the LTPA Key in the Fully Qualified Key File Name field.
•      Click Import Keys.
•      Click OK and save the changes to the master configuration.
•       Restart both the server for which we have exported the LTPA Key from and the server into which we imported the LTPA Key. Restart the servers only after the import of the LTPA Keys into all the servers for which we planned to establish the SSO.

Repeat the same steps above for all the servers for which we need to enable the SSO, and then restart all the servers.

Verification: To verify the changes were successful, navigate to one of the servers (using the fully qualified host name) and authenticate. Now, try going to the second server and you should be authenticated automatically without a login prompt.

Note: Using localhost, a short host name, or the IP address in place of the host name is not recommended. Single sign-on requires that the browser pass LTPA cookies to the WebSphere Application Server, and these cookies contain the fully qualified host name.

plugin-cfg.xml file

The Web Server plug-in uses an XML configuration file to determine whether a request is for the Web Server of the application server. When a request reaches the Web Server, the URL is compared to those managed by the plug-in. If a match is found, the plug-in configuration file contains the information needed to forward the request to the web container using the web container inbound chain.

Sample plugin-cfg.xml file:

This code is an example of the contents of the plugin-cfg.xml configuration file after it has been updated by the application server. Depending on your application server configuration, the contents of your plugin-cfg.xml file may differ from this example.
In this example, MYSYSTEM is the name of the machine that hosts the application server and the Web server.

<?xml version="1.0" encoding="ISO-8859-1"?>

<Config ASDisableNagle="false" AcceptAllContent="false"

    IISDisableNagle="false" IgnoreDNSFailures="false"

    RefreshInterval="60" ResponseChunkSize="64">

  <Log LogLevel="Error" Name="/QIBM/UserData/WebASE51/ASE/

      default/logs/http_plugin.log"/>

  <Property Name="ESIEnable" Value="true"/>

  <Property Name="ESIMaxCacheSize" Value="1024"/>

  <Property Name="ESIInvalidationMonitor" Value="false"/>

  <VirtualHostGroup Name="default_host">

    <VirtualHost Name="*:13341"/>

    <VirtualHost Name="*:80"/>

  </VirtualHostGroup>

  <ServerCluster CloneSeparatorChange="false" LoadBalance="Round Robin"

      Name="server1_MYSYSTEM_default_Cluster" PostSizeLimit="-1"

      RemoveSpecialHeaders="true" RetryInterval="60">

    <Server ConnectTimeout="0" ExtendedHandshake="false"

        MaxConnections="-1" Name="MYSYSTEM_default_server1"

        WaitForContinue="false">

      <Transport Hostname="MYSYSTEM.RCHLAND.IBM.COM" Port="13341"

          Protocol="http"/>

      <Transport Hostname="MYSYSTEM.RCHLAND.IBM.COM" Port="13353"

          Protocol="https">

        <Property Name="keyring" Value="/QIBM/UserData/WebASE51/ASE/

            default/etc/plugin-key.kdb"/>

        <Property Name="stashfile" Value="/QIBM/UserData/WebASE51/ASE/

            default/etc/plugin-key.sth"/>

      </Transport>

    </Server>

      <PrimaryServers>

        <Server Name="MYSYSTEM_default_server1"/>

      </PrimaryServers>

  </ServerCluster>

  <UriGroup Name="default_host_server1_MYSYSTEM_default_Cluster_URIs">

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="/snoop/*"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="/hello"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="/hitcount"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="*.jsp"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="*.jsv"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="*.jsw"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="/j_security_check"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="/ibm_security_logout"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="/servlet/*"/>

    <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid"

        Name="/ivt/*"/>

  </UriGroup>

  <Route ServerCluster="server1_MYSYSTEM_default_Cluster"

      UriGroup="default_host_server1_MYSYSTEM_default_Cluster_URIs"

      VirtualHostGroup="default_host"/>

  <RequestMetrics armEnabled="false" newBehavior="false"

      rmEnabled="false" traceLevel="HOPS">

    <filters enable="false" type="URI">

      <filterValues enable="false" value="/servlet/snoop"/>

      <filterValues enable="false" value="/webapp/examples/HitCount"/>

    </filters>

    <filters enable="false" type="SOURCE_IP">

      <filterValues enable="false" value="255.255.255.255"/>

      <filterValues enable="false" value="254.254.254.254"/>

    </filters>

  </RequestMetrics>

</Config>

The plugin-cfg.xml file

The plugin-cfg.xml file includes the following elements and attributes. Unless indicated otherwise, each element and attribute can be specified only once within the plugin-cfg.xml file. For a sample plugin-cfg.xml file, see Sample plugin-cfg.xml file.

Config  This element is required. It indicates the beginning of the WebSphere HTTP plug-in configuration file, and contains all of the other elements in the file. It can include one or more of the following attributes and elements:

·         IgnoreDNSFailures attribute  This attribute pecifies whether the plug-in ignores DNS failures within a configuration when the plug-in starts. Valid values aretrue and false. The default value is false.

·        If the value is true, the plug-in ignores DNS failures within a configuration and starts successfully if at least one server in each ServerCluster is able to resolve the host name. Any server for which the host name cannot be resolved is marked unavailable for the duration of the configuration. The plug-in does not make additional attempts to resolve the host name. If a DNS failure occurs, a log message is written to the plug-in log file and the plug-in initialization continues.

·        If the value is false, the Web server does not start if any DNS failures are detected.

·         RefreshInterval attribute  This attribute specifies the time interval in seconds at which the plug-in should check the configuration file to see if the file is changed. The plug-in checks the file for any modifications that have occurred since the last time the plug-in configuration was loaded. The default value is 60.

In a development environment, where changes can occur frequently, a lower setting is preferable. In production, a higher value than the default is preferable because updates to the configuration do not occur often. If the plug-in fails to reload, a message is written to the plug-in log file and the existing configuration is used until the plug-in configuration file successfully reloads.

·         ASDisableNagle attribute  This attribute specifies whether to disable nagle algorithm for the connection between the plug-in and the application server. By default, nagle algorithm is enabled. Valid values are true and false.

·         IISDisableNagle attribute  This attribute specifies whether to disable nagle algorithm on Microsoft Internet Informations Services (IIS). By default, nagle algorithm is enabled. Valid values are true and false.

·         AppServerPortPreference attribute  This attribute specifies which port number the application server uses to build URIs for a sendRedirect action. Valid values are webserverPort and hostHeader. The default value is webserverPort.

·        If you specify a value of webserverPort, the server uses the port number from the host header of the incoming HTTP request.

·        If you specify a value of hostHeader, the server uses the port number on which the Web server received the request.

·         VHostMatchingCompat attribute  The Config element can contain no more than one VHostMatchingCompat attribute. This attribute specifies that the port number is to be used for virtual host matching. Valid values are true and false. The default value is false.

·        If you specify a value of true, matching is done based on the port number for which the request was received.

·        If you specify a value of false, matching is done based on the port number contained in the host header.

·         ResponseChunkSize attribute  When a response is returned to the Web server, the plug-in reads the response body in chunks until all of the response data is read. This attribute specifies the maximum size of these chunks in kilobytes. The default value is 64. Note that if the response body contains a large amount of data, you might experience a decrease in performance.

For a chunk size of n KB, the plug-in reads responses according to these conditions:

·        If the content length of the response body is unknown, a buffer size of N kilobytes is allocated and the body is read in N kilobyte 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.

·         AcceptAllContent attribute  This attribute specifies whether or not 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. Valid values are true and false. The default value isfalse.

·        Specify a value of true if content is to be expected and read for all requests

·        Specify a value of false if content is to be expected and read for only POST and PUT requests.

·         ChunkedResponse attribute  This attribute specifies whether or not the plug-in chunks the response to the client when Transfer-Encoding : Chunked response header is present in the response. This attribute applies only to the IIS, IPlanet, and Domino Web servers. The IHS Web server automatically handles the chunking of the response to the client. Valid values are true and false. The default value is false.

·        If you specify a value of true, the plug-in chunks the response to the client.

·        If you specify a value of false, the plug-in does not chunk the response.

·         IISPluginPriority attribute  This attribute specifies the priority in which the IIS Web server loads the Web server plug-in. Valid values are High, Medium, and Low. The default value is High.

NOTES:

·        The IIS Web server uses this value during startup. If you change this attribute, you must restart the Web server for the change to take effect.

·        The default value of High ensures that all requests are handled by the Web server plug-in before they are handled by any other filters or extensions. If you experience problems when you set the value to Medium or Low, rearrange the priorities or change the priority of the other filters or extensions.

·         Log element  The Log element describes the location and level of log messages that the plug-in writes.

The Log element can include these attributes:

·        Name attribute  The Log element includes exactly one Name attribute. This attribute specifies the fully qualified path to the log file. If the file does not exist, it is created. If the file exists, new log messages are appended to the file.

·        LogLevel attribute  The Log element can include no more than one LogLevel attribute. This attribute specifies the level of detail of the log messages that the plug-in writes to the log. You can specify one of the following values for this attribute:

·         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.

The default value is Error, and this value is used if a LogLevel attribute is not specified for the Log element. As an example, you might specify the LogLevel as:

<Log LogLevel="Error" Name=

     "/QIBM/UserData/WebAS51/Base/myInstance/logs/http_plugin.log"/>

Note: The Trace level generates a large amount of messages. It is recommended that you use the Trace level only for troubleshooting purposes.

·         Property Name="esiEnable" Value="true/false" element  This element enables or disables the Edge Side Include (ESI) processor. If the ESI processor is disabled, the other ESI elements in this file are ignored. Valid values are true and false. The default value is true.

·         Property Name="esiMaxCacheSize" Value="integer" element  The Value attribute of this element specifies the maximum size of the cache, in kilobytes (KB). The default value 1024, which is equivalent to 1 megabyte. When the cache is full, entries are removed based on their expiration times.

·         Property Name="ESIInvalidationMonitor" Value="true/false" element  This element indicates whether or not the ESI processor receives invalidations from the application server. Valid values aretrue and false. The default value is false.

·         ServerCluster element  The Config element can contain one or more ServerCluster elements. The ServerCluster element specifies a group of servers that are generally configured to service the same types of requests. 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 uses load-balancing across the defined servers. The plug-in can use a round robin algorithm or a random algorithm. The following example is an example of a ServerCluster element:

<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="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>

    </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="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>

    </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="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>

    </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="/QIBM/UserData/WebASE51/ASE/default/etc/keyring.kdb"/>

    </Transport>

  </Server>

  <PrimaryServers>

    <Server Name="Server1"/>

    <Server Name="Server2"/>

  </PrimaryServers>

  <BackupServers>

    <Server Name="Server3"/>

  </BackupServers>

</ServerCluster>

The ServerCluster element can include these attributes and elements:

·        Name attribute  Each ServerCluster element includes exactly one Name attribute. This attribute specifies the logical or administrative name for this group of servers.

·        LoadBalance attribute  Each ServerCluster element can include no more than one LoadBalance attribute. This attribute specifies the type of load balancing that the plug-in uses. Valid values are Round Robin and Random. The default value is Round Robin. In round robin load-balancing, the first server is selected randomly. For subsequent requests, servers are selected in a specified order, unless a server is busy. If a server is busy, the next available server in the sequence is selected. This implementation ensures that in multiple process-based Web servers, all of the processes do not send their first request to the same application server.

·        RetryInterval attribute  Each ServerCluster element can include no more than one RetryInterval attribute. This attribute specifies the length of the interval, in seconds, between attempts to connect to an unavailable server. The default value is 60.

·        RemoveSpecialHeaders attribute  Each ServerCluster element can include no more than one RemoveSpecialHeaders attribute. The plug-in adds special headers to the request before it forwards the request to the application server. These headers store information that the application needs when it processes the request. If the incoming request contains headers, the plug-in removes the existing headers and adds new headers before it sends the request to an application server.

Valid values are true and false. The default value is true. Setting the attribute to false introduces a potential security exposure by not removing headers from incoming requests.

·        CloneSeparatorChange attribute  Each ServerCluster element can include no more than one CloneSeparatorChange attribute. Some pervasive devices cannot handle the colon character (:) that is used to separate clone IDs in conjunction with session affinity. This attribute specifies that clone IDs are separated with a plus character (+). You must also change application server configurations so that the application server uses the plus character to separate clone IDs. Valid values are true andfalse. The default value is false.

·        PostSizeLimit attribute  Each ServerCluster element contains no more than one PostSizeLimit attribute. If a request exceeds a specified size, the plug-in does not send the request to an application server. This attribute specifies the maximum request size in bytes. The default value is -1, which indicates that there is no size limit.

·        Server element  Each ServerCluster element contains one or more Server elements. This element specifies an application server instance that is configured to handle requests routed to it based on the routing rules of the plug-in configuration. The Server element corresponds to an application server that runs on the local machine or a remote machine.

The Server element can contain these attributes and elements:

·         Name attribute  Each Server element includes exactly one Name attribute. This attribute specifies the administrative or logical name for the server.

·         CloneID attribute  Each Server element includes no more than one CloneID attribute. This attribute is used in conjunction with session affinity. If this unique ID is present in the HTTP cookie header of a request or the URL (if you use URL rewriting), the plug-in routes the request to the designated server, provided all other routing rules are met. If a CloneID is not specified in the Server element, then session affinity is not enabled for this server.

If this attribute is specified, the plug-in checks the incoming cookie header or URL for JSESSIONID. If JSESSIONID is found then the plug-in looks for one or more clone IDs. If a clone ID is present, and a matching ID is specified in the plug-in configuration file, then the request is routed to the specified application server, regardless of the load balancing configuration for the cluster.

If you are not using session affinity, it is recommended that you remove the CloneID attributes from the configuration file. If the attribute is specified, the plug-in performs additional request processing. If clone IDs are not specified in the configuration, the plug-in routes the request according to the load balancing configuration for the cluster.

·         WaitForContinue attribute  Each Server element includes no more than one WaitForContinue attribute. This attribute specifies whether the plug-in uses the HTTP 1.1 100 Continue support before it sends the request content to the application server. Valid values are true and false. The default value is false. The plug-in does not wait for the 100 Continue response from the application server before it sends the request content. For performance reasons, it is recommended that you enable this function only if you are configuring the plug-in to work with certain types of proxy firewalls.

·          LoadBalanceWeight attribute  Each Server element includes no more than one LoadBalanceWeight attribute. This attribute specifies the weight associated with the application server for weighted round-robin load balancing. The algorithm for this attribute decrements all weights within the server cluster until all of the weights reach zero. When a server's weight reaches zero, no more requests are routed to that server until all of the servers in the cluster have a weight of zero. After all servers reach zero, the weights for all servers in the cluster are reset and the algorithm starts over.

When an application server is shut down, it is recommended that you set the weight for that server to zero. The plug-in can maintain proper load balancing among the remaining servers.

·         ConnectTimeout attribute  Each Server element includes no more than one ConnectTimout attribute. The ConnectTimeout attribute of a Server element 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.

If no ConnectTimeout value is specified, the plug-in performs a blocking connect in which the plug-in sits until an operating system times out and allows the plug-in to designate the server as 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.

·         ExtendedHandshake attribute  Each Server element includes no more than one ExtendedHandshake attribute. If a proxy firewall is between the Web server plug-in and the application server, and an application server fails, the plug-in can still connect successfully with the firewall. As a result, the plug-in does not detect that the application server is not running. If you set the ExtendedHandshake attribute to true, the plug-in performs some communication with the application server to ensure that the application server is running. If the application server is not running, the plug-in can route the request to a different server.

Valid values are true and false. The default value is false.

·         MaxConnections attribute  Each Server element includes one MaxConnections attribute. This attribute specifies the maximum number of pending connections to an application server that can be flowing through a Web server process at any point in time. For example, in the following situation, the application server could receive up to 500 connections. The application server can receive 50 connections from each process, and there are 10 processes.

·      The application server is fronted by 5 nodes that are running an IBM HTTP Server Web server instance.

·      Each node starts 2 processes.

·      The MaxConnections attribute is set to 50.

The default value for this attribute is -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 element  Each Server element contains one or more Transport elements. This element specifies the transport for reading and writing requests to a particular application server instance. The transport provides the information needed to determine the location of the application server to which the request is sent. If multiple transports are configured to use the same protocol, the first one is used.

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.

The Transport element can include these attributes and elements:

·      Hostname attribute  Each Transport element includes exactly one Hostname attribute. This attribute specifies the host name or IP address of the machine where the application server instance is running.

·      Port attribute  Each Transport element includes exactly one Port attribute. This attribute specifies the port on which the application server instance listens for incoming requests.

·      Protocol attribute  Each Transport element includes exactly one Protocol attribute. This attribute specifies the protocol that the plug-in uses to communicate over this transport. Valid values are HTTP and HTTPS.

·      Property element  Each Transport element can contain zero or more Property elements. If the protocol for the transport is HTTPS, the Property element specifies initialization parameters, such as password and keyring.

The Property element can include these attributes:

·         Name attribute  Each Property element includes exactly one Name attribute. This attribute specifies the name of the Property being defined. Valid values are password, keyring, and stashfile.

·         Value attribute  Each Property element includes exactly one Value attribute. This attribute specifies the value of the Property.

For example, this section of the plugin_cfg.xml file might look like this:

  <Transport Hostname="192.168.1.2" Port="9443" Protocol="HTTPS">

      <Property Name="keyring"

        value="/QIBM/UserData/WebAS51/Base/myInstance/etc/keyring.kdb"/>

      <Property Name="stashfile"

        svalue="QIBM/UserData/WebAS51/Base/instance/etc/keyring.sth"/>

      <Property Name="password" value="WebAS"/>

  </Transport>

·        ClusterAddress element  Each ServerCluster element contains no more than one ClusterAddress element. Use a ClusterAddress if you do not want the plug-in to perform any type of load balancing because you have a separate type of load balancing between the plug-in and the application server.

If you include the ClusterAddress, requests that do not have affinity established are routed to the ClusterAddress. If affinity has been established, the plug-in bypasses the ClusterAddress and routes the request to the appropriate application server. If no ClusterAddress is defined for the ServerCluster, the plug-in distributes uses its load balancing configuration to distribute requests among the servers listed in the PrimaryServers element. The ClusterAddress element can include the same attributes and elements that the Server element uses. For a description of these attributes and elements, see Server element.

·        PrimaryServers element  Each ServerCluster element contains no more than one PrimaryServers element. This element lists application servers to which the plug-in routes requests for this cluster. If a list of PrimaryServers is not specified, the plug-in routes requests to the servers that are defined for the ServerCluster.

·        BackupServers element  Each ServerCluster element contains no more than one BackupServers element. This element lists servers to which the plug-in routes requests if all of the servers that are specified in the PrimaryServers list are unavailable. The plug-in does not use load balancing for the servers in the BackupServers list. Instead, the plug-in attempts to send the request to each backup server in the order that they appear in this list. The plug-in routes requests to the first available application server from the BackupServers list. If no backup servers are available, the plug-in returns an error.

·         VirtualHostGroup element  The VirtualHostGroup element specifies a group of virtual host names that are included in the HTTP Host header. You can use this element to group virtual host definitions that are configured to handle similar types of requests. The following example is an example of a VirtualHost Group element and associated elements and attributes:

·        <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>

The VirtualHostGroup element includes these attributes and elements:

·        Name attribute  The VirtualHostGroup includes exactly one Name attribute. This attribute specifies the logical or administrative name to be used for this group of virtual hosts.

·        VirtualHost element  The VirtualHostGroup element contains one or more VirtualHost elements. This element specifies the host name that determines whether incoming requests are routed to an application server. The host names are part of the HTTP Host header.

The VirtualHost element includes this attribute:

·         Name attribute  Each VirtualHost element includes exactly one Name attribute. This attribute specifies the host name and port number that is specified in the HTTP Host header to match successfully with this VirtualHost. The value is a host name or IP address and port combination, separated by a colon.

You can specify host names and ports, or you can specify an asterisk (*) for the host name, port, or both. If you specify an asterisk for both the host and the port number, any request matches this rule. If no port is specified in the definition, the plug-in uses the default HTTP port (80).

·         UriGroup element  The UriGroup element specifies a group of URIs that can be specified on the HTTP request line. The plug-in compares the incoming URI with the URIs in the group to determine whether or not the application server can process the request. The Route element links the URI group to a server cluster and a virtual host group that are eligible to serve this group of URIs. The following example is an example of a UriGroup element and associated elements and attributes:

·        <UriGroup Name="Uris">

·            <Uri Name="/servlet/snoop"/>

·            <Uri Name="/webapp/*"/>

·            <Uri Name="*.jsp"/>

</UriGroup>

The UriGroup element can include these attributes and elements:

·        Name attribute  The UriGroup element contains exactly one Name attribute. This attribute specifies the logical or administrative name for this group of URIs.

·        Uri element  The UriGroup element contains one or more Uri elements. This element specifies the virtual path to the resource that you want the application server to process. Each URI specifies the incoming URLs that the application server can process.

The Uri element can include these attributes:

·         Name attribute  Each Uri element includes exactly one Name attribute. To access the URI, the HTTP request line must include the string that is specified for this attribute. You can use an asterisk (*) as a wildcard character within the URI definition. For example, you can specify that URIs such as *.jsp or /servlet/* are to be routed to the application server.

When you assemble your application, you can specify File Serving Enabled or Serve servlets by classname. If you specify File Serving Enabled, then only a wildcard URI is generated for the Web application, regardless of any explicit servlet mappings. If you specify Serve servlets by classname, then this URI is generated: <Uri Name="Web_application_URI/servlet/*">.

·         AffinityCookie attribute  The Uri element includes no more than one AffinityCookie attribute. This attribute specifies the name of the cookie that the plug-in uses when it determines if the inbound request has session affinity to a particular cluster member. The default value is JSESSIONID. For more information about session affinity, see the CloneID attribute.

·         Route element  This attribute specifies a request routing rule. The plug-in uses this rule to determine if an incoming request should be sent to an application server. The Route element specifies how the plug-in handles requests based on certain characteristics of the request. The route definition refers to the other main elements of the plugin-cfg.xml file: a required ServerCluster, and either a VirtualHostGroup, UriGroup, or both.

Using the information that is defined in the VirtualHostGroup and the UriGroup for the route, the plug-in determines if the incoming request to the Web server should be sent on to the ServerCluster defined in this route. The following example is an example of this element:

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

The Route element can contain these attributes:

·        VirtualHostGroup attribute  The Route element includes no more than one VirtualHostGroup attribute. This attribute specifies the group of virtual hosts that the plug-in uses to determine the route. To determine if this request should be handled by the application server, the plug-in compares the incoming host header and server port to the virtual hosts in the specified group. If this attribute is not included in the configuration file, then every request is a successful match.

·        UriGroup attribute  The Route element includes no more than one UriGroup attribute. This attribute specifies the group of URIs that the plug-in uses to determine the route. The plug-in compares the incoming URI for the request to the defined URIs in the specified URI group to determine if this request should be handled by the application server. If this attribute is not included in the configuration file, then every request is a successful match.

·        ServerCluster attribute  The Route element includes exactly one ServerCluster attribute. This attribute specifies the cluster to which the plug-in sends requests that match the route. If both the URI matching and the virtual host matching are successful for this route, the request is sent to one of the servers defined within the specified cluster.

·         RequestMetrics element  This element specifies whether or not Request Metrics is      enabled, and how to filter the requests based on the Internet protocol (IP) and Uniform Resource Identifiers (URI) filters. The following example is an example of this element:

·        <RequestMetrics armEnabled="false" newBehavior="false"

  rmEnabled="false" traceLevel="PERF_DEBUG">

The RequestMetrics element can include these attributes and elements:

·        armEnabled attribute  The RequestMetrics element includes no more than one armEnabled attribute. This attribute indicates whether or not the ARM 4 agent is enabled in the plug-in. Valid values are true and false. The default value is false. In WebSphere Application Server - Express Version 5.1, the plug-in ignores this attribute.

Note: To enable ARM 4 support for the SunOne (iPlanet) Web server, you must include the AddLog fn="as_term"directive in the obj.conf file.

·        loggingEnabled attribute  The RequestMetrics element includes exactly one newBehavior attribute. This attribute indicates whether or not request metrics logging is enabled in the plug-in. Valid values are true and false. When this value is set to true and the traceLevel attribute is not set to NONE, request metrics data is logged. When this value is set to false, request logging is disabled. 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 totrue. In WebSphere Application Server - Express Version 5.1, the plug-in ignores this attribute.

·        rmEnabled attribute  The RequestMetrics element includes exactly one rmEnabled attribute. This attribute specifies whether or not Request Metrics is enabled in the plug-in. Valid values are true and false. The default value is false.

·         If the value for this attribute is true, the plug-in Request Metrics filters requests. For requests that pass the filters, the plug-in writes the trace record in the plug-in log file.

·         If the value for this attribute is false, Request Metrics is disabled, and the other attributes and elements for the RequestMetrics element are ignored.

·        traceLevel attribute  The RequestMetrics element includes exactly one traceLevel attribute. This attribute indicates how much information is logged. Valid values are NONE, HOPS, PERF_DEBUG, and DEBUG.

·         A value of NONE specifies that no trace information is logged.

·         A value of HOPS specifies that trace information is logged only for major process hops.

·         A value of PERF_DEBUG specifies that information is logged in addition to major hops.

·         A value of DEBUG specifies that a full detailed trace is recorded.

When this attribute is set to NONE, there is request logging is disabled. When this attribute is not set to NONE, request information is logged after the request is processed.

·        filters element  The RequestMetrics element includes no more than two filters elements. The filters control which requests are traced.

Each filters element includes these attributes and elements:

·         enable attribute  Each filters element includes exactly one enable attribute. Valid values are true and false. The default value isfalse. If the value is true, the type of filter is enabled, and RequestMetrics traces requests that match a filterValues element.

·         type attribute  Each filters element includes exactly one type attribute. Valid values are SOURCE_IP and URI.

·         filterValues element  The filters element includes one or more filterValues elements. The filterValues show the detailed filter information.

The filterValues element includes these attributes:

·      enable attribute  Each filterValues element includes exactly one enable attribute. Valid values are true and false. The default value is false. If the value is true, the filter is enabled, and RequestMetrics traces requests that match the value attribute.

·      value attribute  Each filterValues element includes exactly one value attribute. This attribute specifies the filter value for the corresponding filter type. Specify either an IP address or a URI.

·         For the SOURCE_IP filter type, requests are filtered based on the client IP address. You 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, as in these examples: 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 URI and client IP address filters are enabled, Request Metrics requires a match for both filter types. If neither is enabled, all requests are considered a match.