How to Delete Websphere Application Server Profile

Here we are going to discuss how to delete the profile in Websphere Application server environment. I used the following to remove application server profile.

Note: Before deleting profile we need to stop all services associate with it.

e.g. Stop the Application server and webServer if configured.

Procedure:

1. First list all profiles on a server:
   List the profile using one of these commands
   Windows: was_install_dir\bin\manageprofiles.bat –listProfiles
   UNIX/Linux: was_install_dir/bin/manageprofiles.sh –listProfiles
2. Remove a WebSphere Application Server profile:
   Delete the profile using one of these commands:
   On Windows: was_install_dir\bin\manageprofiles.bat –delete –profileName profile
   On UNIX/Linux: was_install_dir/bin/manageprofiles.sh –delete –profileName profile
3. Ensure that references to the deleted profile are removed from the profile registry by running the following command:
   On Windows: was_install_dir\bin\manageprofiles.bat –validateAndUpdateRegistry
   On UNIX/Linux: was_install_dir/bin/manageprofiles.sh –validateAndUpdateRegistry
4. Delete the profile directory tree (if it was not deleted by the previous action).
   Delete the profile Directory using one of these commands:
   On Windows: was_install_dir\profiles\rmdir /s profileDirectory
   On UNIX/Linux: was_install_dir\profiles\rm -R profileDirectory

Hope this will help you to delete the profile in your environment and for more option of manageprofile run the command manageprofiles.bat –help

LDAP in-detailed

Configuring Lightweight Directory Access Protocol user registries

To access a user registry using the Lightweight Directory Access Protocol (LDAP), you must know a valid user name (ID) and password, the server host and port of the registry server, the base distinguished name (DN) and, if necessary, the bind DN and the bind password. You can choose any valid user in the user registry that is searchable. You can use any user ID that has the administrative role to log in.

Before you begin

In some LDAP servers, administrative users cannot be searched and thus cannot be used, for example, when cn=root in Tivoli Access Manager. The user is referred to as a WebSphere Application Server security server ID, server ID, or server user ID in the documentation. A server ID user has special privileges when calling some protected internal methods.
Normally, the server ID and password are used to log into the administrative console after you turn on security.
When security is enabled in the product, the primary administrative user name and password are authenticated with the registry during the product startup. If authentication fails, the server does not start. It is important to choose an ID and password that do not expire or change often. If the product server user ID or password need to change in the registry, make sure that the changes are performed when all the product servers are up and running. When changes are to be made in the registry, review the article on Lightweight Directory Access Protocol user registries (LDAP) before beginning this task.

Procedure

1. In the administrative console, click Security > Global security.
2. Under User registries, click LDAP.
3. Enter a valid user name in the Server user ID field. You can either enter the complete distinguished name (DN) of the user or the short name of the user, as defined by the user filter in the Advanced LDAP settings panel. For example, enter the user ID for Netscape browsers. This ID is the security server ID, which is only used for WebSphere Application Server security and is not associated with the system process that runs the server. The server calls the local OS registry to authenticate and obtain privilege information about users by calling the native application programming interfaces (API) in that particular registry.
4. Enter the password of the user in the Server user password field.
5. Select the type of LDAP server to use from the Type list. The type of LDAP server determines the default filters that are used by WebSphere Application Server. These default filters change the Typefield to Custom, which indicates that custom filters are used. This action occurs after you click OK orApply in the Advanced LDAP settings panel. Choose the Custom type from the list and modify the user and group filters to use other LDAP servers, if required.IBM Tivoli Directory Server users can choose IBM Tivoli Directory Server as the directory type. Use the IBM Tivoli Directory Server directory type for better performance. For a list of supported LDAP servers, see the Supported hardware, software, and APIs Web site.
6. Enter the fully qualified host name of the LDAP server in the Host field. You can enter either the IP address or domain name system (DNS) name.
7. Enter the LDAP server port number in the Port field. The host name and the port number represent the realm for this LDAP server in the WebSphere Application Server cell. So, if servers in different cells are communicating with each other using Lightweight Third Party Authentication (LTPA) tokens, these realms must match exactly in all the cells.The default value is 389. If multiple WebSphere Application Servers are installed and configured to run in the same single sign-on domain, or if the WebSphere Application Server interoperates with a previous version of the WebSphere Application Server, then it is important that the port number match all configurations. For example, if the LDAP port is explicitly specified as 389 in a version 5.xconfiguration, and a WebSphere Application Server at version 6.0.x is going to interoperate with the version 5.x server, then verify that port 389 is specified explicitly for the version 6.0.x server.
8. Enter the base distinguished name (DN) in the Base distinguished name field. The base DN indicates the starting point for searches in this LDAP directory server. For example, for a user with a DN of cn=John Doe, ou=Rochester, o=IBM, c=US, specify the base DN as any of the following options assuming a suffix of c=us): ou=Rochester, o=IBM, c=us or o=IBM c=us or c=us. For authorization purposes, this field is case sensitive by default. Match the case in your directory server. If a token is received (for example, from another cell or Lotus Domino) the base DN in the server must match exactly the base DN from the other cell or Domino. If case sensitivity is not a consideration for authorization, enable the Ignore case for authorization option.In WebSphere Application Server, the distinguished name is normalized according to the Lightweight Directory Access Protocol (LDAP) specification. Normalization consists of removing spaces in the base distinguished name before or after commas and equal symbols. An example of a non-normalized base distinguished name is o = ibm, c = us or o=ibm, c=us. An example of a normalized base distinguished name is o=ibm,c=us.
   To interoperate between WebSphere Application Server Version 5 and later versions, you must enter a normalized base distinguished name in the Base Distinguished Name field. In WebSphere Application Server, Version 5.0.1 or later, the normalization occurs automatically during runtime.
   This field is required for all LDAP directories except the Lotus Domino Directory. The Base Distinguished Name field is optional for the Domino server.
9. Optional: Enter the bind DN name in the Bind distinguished name field. The bind DN is required if anonymous binds are not possible on the LDAP server to obtain user and group information. If the LDAP server is set up to use anonymous binds, leave this field blank. If a name is not specified, the application server binds anonymously. See the Base Distinguished Name field description for examples of distinguished names.
10. Optional: Enter the password corresponding to the bind DN in the Bind password field.
11. Optional: Modify the Search time out value. This timeout value is the maximum amount of time that the LDAP server waits to send a response to the product client before stopping the request. The default is 120 seconds.
12. Ensure that the Reuse connection option is selected. This option specifies that the server should reuse the LDAP connection. Clear this option only in rare situations where a router is used to send requests to multiple LDAP servers and when the router does not support affinity. Leave this option selected for all other situations.
13. Optional: Verify that the Ignore case for authorization option is enabled. When you enable this option, the authorization check is case insensitive. Normally, an authorization check involves checking the complete DN of a user, which is unique in the LDAP server and is case sensitive. However, when you use either the IBM Directory Server or the Sun ONE (formerly iPlanet) Directory Server LDAP servers, you must enable this option because the group information that is obtained from the LDAP servers is not consistent in case. This inconsistency affects the authorization check only. Otherwise, this field is optional and can be enabled when a case sensitive authorization check is required. For example, you might select this option when you use certificates and the certificate contents do not match the case of the entry in the LDAP server.You can also enable the Ignore case for authorization option when you are using single sign-on (SSO) between the product and Lotus Domino. The default is enabled.
14. Optional: Select the SSL enabled option if you want to use Secure Sockets Layer communications with the LDAP server.If you select the SSL enabled option, select the appropriate SSL alias configuration from the list in the SSL configuration field. For more information on setting up LDAP for SSL, see Configuring Secure Sockets Layer for the Lightweight Directory Access Protocol client .
15. Optional: In the SSL configuration field, select the Secure Sockets Layer configuration to use for the LDAP connection. This configuration is used only when SSL is enabled for LDAP. The default isDefaultSSLSettings. To modify or create a new SSL configuration, click Security > SSL.
16. Click OK. The validation of the user, password, and the setup do not take place in this panel. Validation is only done when you click OK or Apply in the Global Security panel.
    • If you are enabling security for the first time, complete the remaining steps and go to the Global Security panel. Select LDAP as the active user registry.
    • If security is already enabled, but information on this panel changes, go to the Global Security panel and click OK or Apply to validate your changes. If your changes are not validated, the server might not start.

Results

This set of steps is required to set up the LDAP user registry. This step is required as part of enabling security in the WebSphere Application Server.

Bind Distinguished : it means these are the credentials to login to the LDAP server.

Base distinguished: it is a directory, where the search has to start

The BaseDN describes one level of an LDAP container that an object (such a as a user) belongs to.

The Bind DN is the user object (account) that WebSphere uses in order to connect to the repository.

Source : from IBM site.

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.