Install WAS

 

Contents

  1. WAS
  2. Embedded Messaging
  3. Web Server Installation
  4. Install IBM HTTP Server V 2.0.42.x
  5. IBM WAS v5.1 Release Notes

 

See Also

  1. Install II

 

Install WAS

  1. Review hardware and software requirements

  2. Review prerequisites

  3. The WAS installers use the language setting from the machine locale to determine the language for the interface. Note that for Red Hat Linux 9, you can improve performance exponentially by changing the default locale.

  4. Install a Web server on a separate machine. (Optional)

    The installation programs let you install a web server on the same machine as the appserver. If you want the web server on a separate machine, perform this step.

    After installing IBM HTTP Server, you can install the plug-in by installing the base WAS product and deselecting all features but the plug-in for IBM HTTP server.

    You do not have to use a web server. You can instead use a hardware load balancer such as Big-IP F5 or Local Director.

  5. Configure WebSphere MQ.

    This is for enterprise-level implementations.

    To install WAS v5 on a machine that already has WebSphere MQ v5.3, certain prerequisites need to be satisfied.

  6. Verify that no files exist in the $WAS_HOME/classes directory.

  7. To migrate, see WAS 5.0 to 5.1 upgrade.

  8. As user "root", cd to the directory where launchpad.sh is located.

    Failing to use the correct working directory can cause ISMP errors that stop the installation.

  9. Execute ./launchpad.sh.

    The prereqChecker.xml file checks for existing versions of WAS.

    You can start the installation wizard from the command line, bypassing launchpad.sh, by executing ./install.sh.

    Perform a silent installation by running...

    ./install.sh options -responsefile

    ...which causes the installation wizard to read your responses from the options response file, instead of from the interactive GUI. You must customize the response file before installing silently.

  10. Choose Custom install

    This type of installation is required if you intend to deselect the WAS embedded messaging server because you have already installed the WebSphere MQ Version 5.3 product, or another JMS provider. And if you are going enterprise, you want to deselect embedded messaging.

    For better appserver startup times, do not install the Samples.

  11. Examine the $WAS_HOME/logs/log.txt file to verify that there were no file system or other unusual errors during installation.

  12. Apply any relevant fix packs.

  13. Tune performance

 

Embedded Messaging

WAS installs the embedded messaging feature by default for use as the JMS provider. Embedded messaging supports both queues and topics.

Gotcha alert: The WAS embedded messaging client cannot interoperate with a WebSphere MQ JMS provider, due to both licensing and version reasons. An embedded messaging client on host1 cannot put messages onto a WebSphere MQ queue on host2. If you are going to use a WebSphere MQ JMS provider, use the WebSphere MQ client. Install WebSphere MQ before installing WAS, and deselect the embedded messaging feature when installing WAS.

Also note that on UNIX systems there is no way to uninstall the embedded messaging client without wiping the disk clean of all WAS software.

Embedded Messaging is really MQ-lite, and should be avoided if you are going to run an enterprise-level system.

 

Web Server Installation

  1. Execute "LaunchPad" to install the plugin for IBM HTTP Server (IHS).

    To install the IHS and its plug-in on a different machine from the WAS.

    1. Run LaunchPad
    2. Select Custom installation.
    3. Clear all options but the IHS and the plug-in for the IHS.
    4. Complete the installation.

    To use a plugin other than IHS, select the plug-in for a supported Web server on the feature selection page of the installation wizard, and then manually configure the plug-in.

 

Install IBM HTTP Server V 2.0.42.x

To configure...

  1. Install IBM HTTP Server Version 2.0 before installing IBM WAS V5.1

  2. Download IBM HTTP Server V2.0.

  3. Go to the directory where you downloaded and unpacked the file and execute... 

    java -jar setup.jar

    To install IBM HTTP Server V2.0 on UNIX-based platforms without using an X-Windows GUI:

    • To use all installation defaults instead of dialogs 

      java -jar setup.jar -silent

    • To use text-based dialogs 

      java -jar setup.jar -console

  4. When installing WAS 5.1, select the relevant plugin-in.

    mod_was_ap20_http.so Linux and UNIX-based platforms other than HP-UX
    mod_was_ap20_http.sl HP-UX platforms
    mod_was_ap20_http.dll Windows

    You must select the IBM HTTP Server V2.0 plug-in during installation of the base IBM WAS, Version 5.1 product. The installer does not install it when you select the plug-in for IBM HTTP Server, Version 1.3.x as it did in previous releases.

 

IBM WAS v5.1 Release Notes

 

Content

  1. Installation and uninstallation
  2. Application servers
  3. Object request brokers
  4. HTTP server
  5. Application services
  6. EJB modules
  7. Web modules
  8. Assembly tools
  9. Deployment
  10. Messaging and Extended messaging
  11. Data access
  12. Performance data and tools

See Also

  1. Online Documents
  2. Deprecated v5.1 features
  3. Online information center
  4. Support Web Site

 

Installation and uninstallation

 

Install WAS on top of WebSphere MQ

To install WAS v5 on a machine that already has WebSphere MQ v5.3...

  1. Verify the following required WebSphere MQ features are installed:

    WAS ND: Java Messaging
    WAS Base... Runtime, Client, Java Messaging, Message Catalogs

  2. Ensure that WebSphere MQ v5.3 is upgraded to the appropriate prerequisite CSD level 

    - CSD1 for WAS v5.0
- CSD3 for WAS v5.0.1
- CSD4 for WAS v5.0.2
- CSD6 for WAS v5.1

  3. Install the WAS v5 GM release.

  4. Install any appropriate WAS fix packs.

After the initial installation of WebSphere MQ and WAS, service WebSphere MQ independently of the WAS fix packs. For example, apply WebSphere MQ v5.3 CSD6 before upgrading WAS to v5.1.0.5.

 

Login with ssh on Linux

When you install WAS, the following entries are displayed in the SystemOut.log file 

JMSRegistrati A MSGS0601I: WebSphere Embedded Messaging has not been installed
JMSEmbeddedPr A MSGS0050I: Starting the Queue Manager
JMSEmbeddedPr E MSGS0058E: Unable to start the JMS Server as WebSphere Embedded Messaging has not been installed
JMSService    E MSGS0001E: Starting the JMS Server failed with exception: java.lang.Exception: 
MSGS0058E: Unable to start the JMS Server as WebSphere Embedded Messaging has not been installed

Also, the following associated messages are added to the mq_install.log file 

Checking if user "root" is in group "mqm"
wmsetup: date time
ERROR: Group "mqm" exists, id "root" is defined to the group but does not
have the group in its current set of effective groups.
Current group membership is ...
uid=0(root) gid=0(system) groups=2(bin)
You may need to login.
wmsetup: date time
... RC 4 from Check_root
ERROR: User "root" not in group "mqm" 
Check_root mqbrkrs
Checking for group "mqbrkrs" ...
lsgroup returned "mqbrkrs id=203 admin=false users=root adms=root registry=files " RC=0
Checking if user "root" is in group "mqbrkrs"
wmsetup: date time
ERROR: Group "mqbrkrs" exists, id "root" is defined to the group but does not
have the group in its current set of effective groups.
Current group membership is ...
uid=0(root) gid=0(system) groups=2(bin)
You may need to login.
wmsetup: date time
... RC 4 from Check_root
ERROR: User "root" not in group "mqbrkrs"

To prevent this problem, use ssh instead of telnet to log in.

To workaround, run: su -

 

Verify the system cp command when using emacs or other freeware

If you have emacs or other freeware installed on your Linux or UNIX-based system, verify that the system cp command is being used.

  1. Type which cp at the command prompt before running the installation program for a WAS product.

  2. Remove the freeware directory from your PATH if the resulting directory output includes freeware. For example if the output shows /opt/freeware/bin/cp, remove the directory from the PATH.

  3. Install the WAS product.

  4. Add the freeware directory back to the PATH.

If you install with a cp command that is part of a freeware package, the installation completes but the Java 2 SDK that the WAS product installs, which is $WAS_HOME/java, can have missing files. Some required symbolic links can be destroyed. If you remove the freeware cp command from the PATH, you can install the WAS product successfully.

To verify that the Java 2 SDK that WAS installs is working correctly...

cd $WAS_HOME/java/bin ./java -version.

 

Verify that no files exist in the $WAS_HOME/classes directory during installation

The $WAS_HOME/classes directory is reserved for testing and debugging fixes when customers call IBM Support. Having files in the directory during installation can cause various problems depending on the fix left in the directory.

Verify that no files exist in the $WAS_HOME/classes directory.

When IBM Support queues work for you and provides you test or debug fixes, you put the fixes in the $WAS_HOME/classes directory. By default, the $WAS_HOME/classes directory is picked up first in the WAS class path to let it override other classes.

This directory lets you verify or debug a fix. After accepting the test fix or finishing with the debugging of the debug fix, delete the fix from the $WAS_HOME/classes directory to return the system to a working state. If you do not remove such fixes from the $WAS_HOME/classes directory, you can experience errors.

 

Application servers

 

The service shows incorrect status when the log root is changed

The WAS service might go to the started state and then return to the stopped state when you start the WAS service even though the server starts successfully. This change in state might happen if the default log root is altered in the variables.xml config file.

The WAS service cannot find the process ID file (for example, server.pid) to verify that the server starts successfully. The process ID is created relative to the log root.

In order for the WAS service to display the correct status, modify the log root directory in your variable.xml file back to the default log root directory, for example, $WAS_HOME/logs. Otherwise, issue the stopServer command to stop the server... 

$WAS_HOME/bin/stopServer.sh server

 

Object Request Brokers

 

ClassCastExceptions or Delegate not set exceptions

When cycling an application, the ORB creates a new ClientDelegate object, though some existing objects still have references to the old ClientDelegate object. The two objects conflict, allowing calls to go to the wrong underlying servant object, which results in the ClassCastExceptions exceptions or Delegate not set error messages followed by further application failures.

Apply interim fix PQ85782 to fix the problem.

 

HTTP server

  1. Forms Proxy Settings and Proxy Cache do not behave correctly
  2. Using IHS IKEYMAN to create a key database causes a core
  3. Hiding one copy of the OpenSSL module so that Apache Web server can start
  4. Define the name of the WebSEAL HTTP server in lower case
  5. Bringing up the IKEYMAN console with the Conversational Monitoring System option for IHS
  6. Enabling cryptographic hardware

 

Forms Proxy Settings and Proxy Cache do not behave correctly

When using IE v6.0 to view the IBM HTTP Administration server, the Forms Proxy Settings and Proxy Cache do not behave correctly. If you select the radio buttons that display editable fields, the fields do not display.

To work around this problem, use another version of the browser.

 

Using IBM HTTP Server IKEYMAN to create a key database causes a core

A core occurs while using the IKEYMAN or IKEYCMD utility, or during the IHS SSL initialization.

An incompatibility exists between functions in various C or C++ run-time libraries. Depending on the order that the libraries are loaded, a core can occur or IHS fails to initialize. This problem is seen on various RedHat Intel versions.

The GSKit libraries used by the IKEYMAN utility and the IHS SSL module require the C++ library libstdc++-libc6.1-1.so.2 file on the Intel platform and the libstdc++-libc6.1-2.so.3 file on the OS/390 platform. If the libraries do not exist, the IKEYMAN utility might provide only limited functionality and the IHS SSL fails to initialize. If another version of this library, or another library with a common function, loaded first, it might result in the use of an incompatible library routine.

If you encounter this problem on Linux Intel systems, set the environment variable LD_PRELOAD to the following values before starting IHS or IKEYMAN...

export LD_PRELOAD=/usr/lib/libstdc++-libc6.1-1.so.2

This change forces the library to load first when the application starts.

 

Hiding one copy of the OpenSSL module so that Apache Web server can start

Apache Web server fails to start when using the mod_ssl plug-in module and issuing the following command 

apachectl startssl

A problem exists with a single process that has two copies of the OpenSSL modules.

Hide the GSKit copy of the OpenSSL modules by renaming the opt/ibm/gsk7/icc directory to opt/ibm/gsk7/icc_save.

 

Define the name of the WebSEAL HTTP server in lower case

When defining your WebSEAL HTTP Server in the console, define the name of the WebSEAL HTTP Server all in lower case.

To define the name of the WebSEAL server name, click...

LTPA | Trust Association | Interceptors | com.ibm.ws.security.web.WebSealTrustAssociationInterceptor | Custom Properties | com.ibm.websphere.security.webseal.hostnames

 

Enabling cryptographic hardware

The cryptographic token is no longer a separate item on the IKEYMAN GUI menu. It is treated as one of the key store types. You can specify the PKCS11 module name by specifying the property of DEFAULT_CRYPTOGRAPHIC_MODULE in the ikmuser.properties file as before. However, IKEYMAN no longer tries to load the DLL or Library (LIB) at startup time to decide whether to support the cryptographic token. The value of the DEFAULT_CRYPTOGRAPHIC_MODULE property is used only for the default value shown on the GUI.

When you open the Cryptographic Token, IKEYMAN first retrieves the value of the DEFAULT_CRYPTOGRAPHIC_MODULE property in the ikmuser.properties file and pre-fill the value in the File Name and Location fields in the Key Database File > Open dialog box of IKEYMAN GUI. Modify the value in the File Name and Location fields or click the Browse button.

Once the specified DLL or LIB is loaded successfully, you can use IKEYMAN. After opening a cryptographic token successfully, IKEYMAN displays the certificates stored in the cryptographic token.

 

Application services

 

Clean disk cache files after installing fix packs

If the server is configured to use the disk cache, clean the disk cache files because the disk cache files are not compatible to the previous version. Failure to remove the old disk cache files results in a ClassCastException exception in the systemerr.log file when you access the cache from the disk.

To delete the disk cache, perform the following steps:

  1. If you do not know the disk cache offload location, do the following steps:

    1. Open the administrative server.
    2. Click Server | Application Server | server | Dynamic Cache Service
    3. The location is specified in the Disk offload field.

    If the location is not specified, the default directory WebSphere/appserver/your_node/server_name/_dynacache is used.

  2. Verify that the you stop the server and delete all the files under the offload location.

  3. If you use Network Deployment, delete the disk cache files for each server.

 

Transaction service unable to recover

If the transaction service is unable to perform recovery processing as a result of inconsistencies within the recovery log, appservers may fail to start. During startup, appservers attempt to resolve incomplete transactions from previous server runs. If the log is corrupt, you might get the following error message...

"WTRN0019E: The transaction service log file 'name' has become corrupted" (where 'name' is either "partnerlog" or "tranlog")

To fix, delete the transaction log files...

rm -r $WAS_HOME/tranlog/*
...and restart the server.

Apply interim fix PQ80441 to prevent the problem from re-occurring.

To download this interim fix, visit the WAS Support page at the following Web site:

 

EJB modules

 

Single access intent read ahead hint

A single access intent read ahead hint might not refer to the same bean type in more than one relationship. For example, if a Department enterprise bean has a relationship employees with the Employee enterprise bean, and also has a relationship manager with the Employee enterprise bean, then a read ahead hint cannot specify both employees and manager.

 

Assembly tools

 

Help files are viewable only from a locally installed browser

If you access any of the IBM WAS tools from a remote machine, for example, the Assembly Toolkit, the remote browser cannot display the help files. You can only view the help files from a locally installed browser.

To work around this problem, close all the Netscape sessions on the remote machine and click Help. A new Netscape session starts and you can then view the Help files.

 

Assembly Toolkit unsupported types

When configuring a resource reference for an application client module in the Assembly Toolkit, the Type field lists javax.resource.cci.ConnectionFactory as an available resource reference. This type is not supported by the J2EE application client run time. The supported types are:

 

Run the Assembly Toolkit on UNIX platforms causes errors

When you run the Assembly Toolkit on UNIX platforms, a sample of errors that display follows:

...Font specified in font.properties not found [-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific] Font specified in font.properties not found [-urw-itc zapfdingbats-medium-r-normal--*-%d-*-*-p-*-sun-fontspecific] ...

The Assembly Toolkit or installer functions are not affected by these errors. These messages display in the command shell that spawned the Java GUI. You can disregard these messages.

 

Messaging and Extended messaging

 

Embedded JMS provider installation fails

It is possible for the embedded JMS provider installation to fail without any visible warning if the prerequisite checker returns an error that the IBM WAS installation is not expecting. The IBM WAS installation completes, but the JMS provider is not installed.

Look for details in...

/tmp/mq_prereq.log
$WAS_HOME/log/create_mq.log
$WAS_HOME/log/mq_install.log

After correcting, install the embedded JMS provider separately by clicking Custom installation.

 

Embedded JMS server and IBM WAS in a single JVM

In a single server environment, the embedded JMS server and IBM WAS run on the same single JVM. If a MQ native process dies and restarts while the JMS server is running, restart all applicable appservers manually.

In a distributed server environment, the JMS server and the appserver run in separate processes, obviating the need to perform this task.

 

Information know about using server-side and client-side selectors

The default behavior for the internal JMS broker is to use server-side selectors. The default behavior for external brokers is to use client-side selectors. The reason for the latter is that not all brokers support server-side filtering. Those that do, are not all JMS compliant in their implementation process.

 

Component-managed authentication alias not specified

When using JMS, informational messages similar to the following can occur: 

[10/31/02 9:13:20:438 EST] 6a55451c ConnectionFac I J2CA0107I: Component-managed authentication alias not specified

If the named connection factory ends in JMSManagedConnection@nnnn, where nnnn is a multi-digit number, the informational message can be ignored. A connection factory with this type of name is created internally by the JMS server and does not require a component-managed authentication alias.

 

Stopping the queue manager while running the embedded JMS provider stops IBM WAS

When you run the embedded JMS provider and the queue manager stops, IBM WAS is also stopped.

To recover the queue manager and IBM WAS, start the appserver.

 

A NullPointer exception is thrown when several remote clients send requests to a target server with a gateway server between the sender and the receiver in a stress environment

In a stress environment where there are several remote clients sending request to a target server with a gateway server between the sender and the receiver, you might get a NullPointer exception recorded in the SystemOut.log file. The remote clients continue to run over time. Then the embedded MQ server ends without warning and the gateway server stops.

When a fix becomes available, you can download it from the following Web site:

https://www6.software.ibm.com/dl/wsmqcsd/wsmqcsd-p.

 

On Linux/Intel (RedHat V8) platforms, installation of WAS hangs during the embedded messaging installation stage

On Linux (RedHat v8), the installation of WAS hangs during the embedded messaging installation stage. The last line of the mq_install.log is

Install MQSeriesClient-5.3.0-1.i386.rpm MQSeriesMsg_Zh_CN-5.3.0-1.i386.rpm MQSeriesMsg_Zh_TW-5.3.0-1.i386.rpm MQSeriesMsg_de-5.3.0-1.i386.rpm MQSeriesMsg_es-5.3.0-1.i386.rpm MQSeriesMsg_fr-5.3.0-1.i386.rpm MQSeriesMsg_it-5.3.0-1.i386.rpm MQSeriesMsg_ja-5.3.0-1.i386.rpm MQSeriesMsg_ko-5.3.0-1.i386.rpm MQSeriesMsg_pt-5.3.0-1.i386.rpm MQSeriesRuntime-5.3.0-1.i386.rpm MQSeriesSDK-5.3.0-1.i386.rpm MQSeriesJava-5.3.0-1.i386.rpm MQSeriesServer-5.3.0-1.i386.rpm...

The last line of the master install log (/tmp/log.txt) is

(date time), Setup.product.install, com.ibm.wizard.platform.linux.LinuxProductServiceImpl, msg1,installing Exec Action From Directory (mqUnixInstallAction

RPM lock files exist that prevent the product installation from continuing.

For information about solving this problem, see the bugzilla report...

http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=74726

 

Data access

 

Limited connection caching available for servlets

Caching of connection handles across servlet methods is limited to JDBC and JMS resources. Other non-relational resources, such as CICS or IMS, currently cannot have their connection handles cached in a servlet. This limitation only applies to single-threaded servlets since multithreaded servlets do not allow caching of connection handles.

To work around this problem, you need to get, use, and close the connection handle within each method invocation.

 

Misleading scope when installing RAR file at the server level

When installing a RAR file, by clicking...

Resources | Resource Adapters | Install RAR
...the scope defined has no effect on where the RAR file gets installed. You can only install RAR files at the node level.

The scope on the Install RAR page determines the node to install. However, the scope you set on the resource adapters panel determines the scope of the new Resource Adapters, which you can install at the server, node, or cell level.

 

Test connection fails when on node agents

The test connection service operation might fail when the operation occurs on the node agent.

This is because either the data source is defined at the node scope, or because the data source is defined at a server scope and the server is not running. The problem only occurs when an alias is added to the configuration, and then used on a data source for testing, without cycling the node agent.

Run stopNode.sh / startNode.sh to fix.

 

DB2 8.1 client limitations

Limitations exist when you connect a DB2 8.1 client to a back level server, for example, DB2 7.2 FP8, using a DB2 XA data source

If there is no fix pack installed on the client, testing the connection for the data source stops the appserver with no error log if the connection is tested from the console. If it is tested from wsadmin.sh at the command prompt, you can receive the following exceptions 

  wsadmin>$AdminControl testConnection 
    TradeDataSource(cells/DefaultNOde/nodes/Def
    aultNode:resources.xml#DataSource_1056390840594)
    WASX7015E: Exception running command: "$AdminControl testConnection 
    TradeDataSource(cells/DefaultNOde/nodes/DefaultNode:resources.
    xml#DataSource_1056390840594)"
    ; exception information...
    com.ibm.websphere.management.exception.ConnectorNotAvailableException
    org.apache.soap.SOAPException: [SOAPException: faultCode=SOAP-ENV:Client;     
    msg=Connection reset by peer: socket closed;
    targetException=java.net.SocketsException...
    Connection reset by peer: socket closed]

If you install Fix Pack 2 on a DB2 8.1 client, the appserver does not stop, but returns the following error 

  389b0a5 DataSourceCon E DSRA8040I: Failed to connect to the DataSource. 
    Encountered : java.lang.Exception: COM.ibm.db2.jdbc.DB2Exception: [IBM][CLI Driver] 
    SQL30070N "0x1055" Command is not supported. 
    SQLSTATE=58014

Upgrade the DB2 server level to the same level as the DB2 client.

 

DB2 legacy CLI JDBC and DB2 Universal JDBC driver

WAS fails if you use the DB2 legacy CLI-based JDBC driver and the DB2 Universal JDBC driver at the same time. Run the DB2 legacy CLI-based JDBC driver and the DB2 Universal JDBC driver at different times.

 

DB2 V8.1 FP3 Universal JDBC driver type 2 XA data source

Applications might stop when you use the DB2 V8.1 FP3 Universal JDBC driver type 2 XA data source. You might see the following message in the SystemOut.log file

Transaction [transaction number] has timed out after xxx seconds.

This defect is in the DB2 V8.1 FP3 Universal JDBC driver. This defect is fixed in DB2 V8.1 FP4. Upgrade your DB2 database to DB2 V8.1 FP4. If you cannot upgrade your database to DB2 V8.1 FP4, use the legacy CLI driver XA data source.

 

Using the correct user ID and password to connect to the DB2 Universal JDBC driver

If you do not use a user ID and password, or you use some combination of an invalid user ID or password to connect to the DB2 Universal JDBC driver, you still can get the connection. However, when the connection is used in an XA transaction, an XAException exception is displayed with an XAER_PROTO error code .

The DB2 Universal JDBC driver requires the correct user ID and password to acquire a connection that is unlike the legacy CLI driver.

Verify that you use the correct user ID and password to connect to the DB2 Universal JDBC driver. DB2 is aware of the problem.

 

The console no longer displays any deprecated JDBC Provider names

Starting from WAS v5.1, the administrative console no longer displays any deprecated JDBC provider names. The new providers differ only in names from the old deprecated ones. The new providers are more descriptive and less confusing.

The deprecated JDBC pProvider names continue to exist in the jdbc-resource-provider-templates.xml file for migration reasons, for example, for the existing Jacl scripts. However, you can use the new and more descriptive JDBC provider names in the Jacl scripts.

 

NullPointerException if serverName property is not provided

When you create a data source of DB2 Universal JDBC driver and set the driverType property to 4, provide the serverName property.

If you do not provide the serverName property, DB2 throws a NullPointerException instead of an exception with meaningful message.

 

preTestSQLString customer property

When using the pre-test connection function with DB2 Legacy CLI-based type 2 JDBC Provider (JDBC) Driver (XA), you need to provide an SQL statement to the preTestSQLString customer property. If you do not provide an SQL statement to the preTestSQLString customer property, WAS uses the default SQL string for the pre-testing the connection, which might cause applications to throw a javax.transaction.xa.XAException exception.

This is a defect of DB2 Legacy CLI-based type 2 JDBC Driver. DB2 is aware of the problem.

 

ArrayIndexOutOfBoundsException thrown when reading CLOB data

An ArrayIndexOutOfBoundsException exception is thrown when reading the CLOB data from the query result set.

The exception is thrown only when the data being retrieved can be expanded because of the character conversion. A typical scenario that causes this exception is that you retrieve the CLOB data from the query result set as an ASCII stream and then read the stream. The following is an example of the exception trace 

java.lang.ArrayIndexOutOfBoundsException
  at COM.ibm.db2.jdbc.app.DB2InputStream.SQLReadArrayOfByte(Native Method)
  at COM.ibm.db2.jdbc.app.DB2InputStream.read(DB2InputStream.java(Compiled Code))
  at COM.ibm.db2.jdbc.app.DB2InputStream.read(DB2InputStream.java(Compiled Code))

DB2 is aware of the problem. Contact DB2 for this problem.

 

Databases-IBM Cloudscape

  1. Descriptive error messages
  2. driverType data source custom property
  3. Uninstall Cloudscape v5.1.x
  4. DB2 JDBC settings instead of Cloudscape
  5. Accessing the result set after a transaction is committed
  6. Remove "export" keywords to support Cloudscape tools on Solaris

 

No descriptive errors

When running WAS v5.0.2 against the Cloudscape Network Server or the DB2 universal driver, you cannot see the descriptive error messages from the database unless the retrieveMessagesFromServerOnGetMessage data source custom property is set to true. By default, the full message text is not returned to the client when a server-side error occurs. This property is disabled by default.

 

driverType data source with Network Server framework

When running WAS v5.0.2 with Cloudscape using the Network Server framework, you can receive the following exception if you either forget to set the driverType data source custom property or set it to 2

com.ibm..db2.jcc.b.SQLException: Unexpected throwable caught java.lang.UnsatisfiedLinkError: DBConnect

To avoid receiving the exception, set the driverType data source custom property to 4.

 

DB2 JDBC settings instead of Cloudscape

When creating a new Cloudscape JDBC Provider Network Server using the universal JDBC driver provider through the console in WAS v5.0.2, the console fills in the DB2 universal data sources settings by default instead of the Cloudscape Network Server ones. Those settings include:

  1. the DataStoreHelper class

  2. the data source custom properties

The incorrect settings do not include the implementation class, which is just like the DB2 Universal one.

If you want to create the Cloudscape JDBC Provider Network Server using the universal JDBC driver provider, perform the following steps to manually modify the entries in the console:

  1. Change the DataStoreHelper class to 

    com.ibm.websphere.rsadapter.CloudscapeNetworkServerDataStoreHelper

  2. You only need the following custom properties

    driverType 4 (Only valid value for Network Server)
    serverName Server TCP/IP address or name. Required
    databaseName Database name
    retrieveMessagesFromServerOnGetMessage Required by WAS, not the database. Defaults to false by the database. Must be set to true in WAS.

    The following data source custom properties are optional

    portNumber. Port number where Network Server listens for connection requests. Required. Default is port 1527.
    logWriter
    traceLevel
    traceFile
    traceFileAppend
    deferPrepares Works as documented except that the prepare on EXECUTE STATEMENT is never deferred
    resultSetHoldability Defaults to CLOSE_CURSORS_AT_COMMIT for Cloudscape. This is the only valid value for Network Server. Use the JDBC 3.0 API's for setting holdability.
    securityMechanism Network Server supports the following security Mechanisms.

    com.ibm.db2.jcc.DB2BaseDataSource.CLEAR_TEXT_PASSWORD_SECURITY
    com.ibm.db2.jcc.DB2BaseDataSource.ENCRYPTED_PASSWORD_SECURITY

 

Accessing the result set after a transaction is committed

When you run WAS with Cloudscape using the Cloudscape network server framework, Cloudscape throws an exception when you access the result set after the transaction is committed despite the fact that the cursor holdability is false by default.

This problem does not exist when you run in Cloudscape embedded. As this problem has been reported to Cloudscape, you can consult Cloudscape Support.

Ensure that your application does not rely on an exception that is thrown.

 

Remove "export" keywords to support Cloudscape tools on Solaris

Cloudscape tools, for example, ij.sh, cview.sh, sysinfo.sh, startNetworkserver.sh, and stopNetworkserver.sh might not work on the Solaris Operating Environment.

The scripts contain a keyword that is not compatible with the Solaris Operating Environment.

Change the scripts to remove the "export" keyword as indicated in the following example:

Change...

export xyz = abc

...to...

xyz = abc

 

XA transactions and IBM Informix Dynamic Server

XA transactions and IBM Informix Dynamic Server sometimes do not play nice together. Possible exceptions include...

java.sql.SQLException: Could not position within a table
...or...

java.sql.SQLException: Could not do a physical-order read to fetch next row.

Currently, there is no solution for the problem. IBM Informix Dynamic Server is working to resolve the issue.

 

A Web services security enabled application fails to start

A Web services security enabled application fails to start. You can receive an error message similar to the following

WSEC5156E: An exception while retrieving the key from KeyStore object: java.security.UnrecoverableKeyException: Given final block not properly padded

The cause of the problem is that the keypass (password) provided for a particular key in a Key Store is invalid. The Key Store passwords are specified in the KeyLocators elements of the bindings file(s) (ws-security.xml, ibm-webservices-bnd.xmi or ibm-webservicesclient-bnd.xmi).

Check the keypass values for keys specified in the KeyLocators elements of the bindings file(s) and correct any that are incorrect.

 

Web services security is not supported in a pure Java client (also known as a non-managed client)

Web services security is not supported in a pure Java client (also known as a non-managed client). Web services security is only supported in a managed client in WAS v5.0.2 or later.

The Web services security constraints do not apply to the outbound client or Web services acting as the client SOAP message if the application code does not use the J2EE programming model, therefore the J2EE environment (including security handlers) is not available to the client. This includes Web services security. You might configure to digitally sign, encrypt, and generate the security tokens. For the outbound message for a client or Web services acting as a client, the SOAP message is not digitally signed or encrypted and the security is not token inserted into the message.

Change the application to a managed client application and use the J2EE programming model to invoke Web services.

 

AccessControlExceptions exceptions might be reported in the system log file that are associated with the JavaMail-related configuration files

In the system log file, WAS might report AccessControlExceptions exceptions that are associated with certain JavaMail-related configuration files such as .mailcap, mailcap, javamail.providers, and so on.

These exceptions are benign. This is not an application or system problem because the JavaMail anticipates the exceptions and handles them appropriately. The WebSphere SecurityManager is rather verbose in logging possible violations of the Java 2 security access control exceptions.

To reduce this redundant reporting, you can grant read access to each reported JavaMail configuration file. For more information, see information center topics, "AccessControlException" and "Configuring app.policy files."

 

Federal Information Processing Standards are supported in WAS v5.0.2 or later

WAS v5.0.2 or later supports a configuration option to use only Federal Information Processing Standards (FIPS) 140-2 certified cryptography modules including IBM Java Cryptography Extension Federal Information Processing Standards (IBMJCEFIPS) and IBM Java Secure Socket Extension Federal Information Processing Standards (IBMJSSEFIPS).

When WAS v5.0.2 or later has FIPS-certified cryptography modules enabled, it uses the IBMJCEFIPS provider exclusively and does not use the IBMJCE provider. Also, when these cryptography modules are enabled, you can configure WAS to use the IBMJSSEFIPS provider on a per port basis.

The IBMJCEFIPS and IBMJSSEFIPS providers that are packaged in WAS v5.0.2 or later are currently in the FIPS certification process. The IBMJCEFIPS and IBMJSSEFIPS modules in WAS v5.0.2, are being certified using the IBM SDK, Version 1.3.1. The modules are undergoing certification for the Windows and AIX platforms and Solaris Operating System only.

IBM is firmly committed to FIPS certification and to meet the Government Security Standards. The IBMJSSEFIPS and IBMJCEFIPS providers are undergoing FIPS 140-2 certification.

 

Unknown certificate errors using the default dummy key files

SSL interoperability fails with unknown certificate errors using the default dummy key files and trust files between WAS v5.1 and previous releases.

A new dummy certificate is created in WAS v5.1 with a later expiration date. The signer for this certificate is not present in the trust files of previous releases. This missing signer causes unknown certificate errors when making SSL connections between WAS v5.1 and previous releases.

Use the newer dummy key files and trust files in the previous releases for test interoperability. Do not use these default dummy certificates, key stores, and trust stores in production environments. The update installer overwrites these files when an interim fix is applied. The certificates are widely used and considered insecure for any production environment.

 

IBM Developer Kit, JTE V 1.4.x security debug

If Java 2 Security is enabled and IBM Developer Kit, JTE, v 1.4.x Java 2 Security debug parameters...

(-Djava.security.debug=all

...or...

-Djava.security.auth.debug=all or both
... are enabled, a recursive loop results and eventually the WAS crashes with a Java core dump. This problem is recognized in the IBM Developer Kit, Java Technology Edition Version 1.4.x.

Do not use the IBM Developer Kit, JTE v 1.4.x> security debug with the all or domain.

 

Problem exists with a parsing permission that has a trailing space in the permission target name

A problem exists with a parsing permission that has a trailing space in the permission target name.

When a policy has a trailing space in the policy permission target name, the policy fails to parse the permission properly in WAS v5.1 IBM Developer Kit, Java Technology Edition Version 1.4.x. In the following example, note the space before the last quote: * \"*\" " 

grant {
    permission javax.security.auth.PrivateCredentialPermission "javax.resource.spi.security.PasswordCredential * \"*\" ","read";
};

The following exception might display when loading a permission with a trailing space in any of permission attributes 

[9/16/03 16:56:13:112 EDT] 5fff004e WSDynamicPoli E SECJ0197E: 
    Caught Invocation TargetException while constructing the permission object. 
    The exception is java.util.NoSuchElementException
       at java.util.StringTokenizer.nextToken(StringTokenizer.java(Compiled Code))
       at javax.security.auth.PrivateCredentialPermission.init(PrivateCredentialPermission.java:379)
       at javax.security.auth.PrivateCredentialPermission.<init>(PrivateCredentialPermission.java:193)
       at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
       at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:79)
       at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:43)
       at java.lang.reflect.Constructor.newInstance(Constructor.java:313)
       at com.ibm.ws.security.policy.WSDynamicPolicy.getPermissionInstance(WSDynamicPolicy.java:1537)
       at com.ibm.ws.security.policy.WSDynamicPolicy.access$400(WSDynamicPolicy.java:76)
       at com.ibm.ws.security.policy.WSDynamicPolicy$WSPolicyTemplate.add(WSDynamicPolicy.java:1594)
       at com.ibm.ws.security.policy.WSDynamicPolicy$WSPolicyTemplate.access$200(WSDynamicPolicy.java:1550)
       at com.ibm.ws.security.policy.WSDynamicPolicy.loadRAPolicyTemplate(WSDynamicPolicy.java:993)
       at com.ibm.ws.security.policy.WSDynamicPolicy.loadRAPolicyTemplate(WSDynamicPolicy.java:965)
       at com.ibm.ws.security.policy.WSDynamicPolicy.setupPolicy(WSDynamicPolicy.java:583)

If the permission is in a policy file loaded by the IBM Developer Kit, Java Technology Edition Version 1.4.x policy tool, the following message might display 

Errors have occurred while opening the policy configuration. View the warning log for more information.

In the warning log, you might see the following error 

Warning: Invalid argument(s) for constructor: javax.security.auth.PrivateCredentialPermission.

Edit the permission and remove the trailing space. When the trailing space is removed, the permission loads properly 

grant {
    permission javax.security.auth.PrivateCredentialPermission "javax.resource.spi.security.PasswordCredential * \"*\"","read";
}

 

"Signed by " and "JAAS Principal" keywords are not supported in dynamic policy

"Signed by " and "JAAS Principal" keywords are not supported in dynamic policy.

The "Signed By" keyword is not supported in the app.policy, spi.policy, library.policy, was.policy, and filter.policy policy files. But this keyword is supported in the java.policy, server.policy, and client.policy files. The "JAAS Principal" keyword is not supported in the app.policy, spi.policy, library.policy, was.policy, and filter.policy files, but in a Java Authentication and Authorization Service (JAAS) policy file specified by the JVM system property java.security.auth.policy.

Define grant statements with the "Signed By" keyword in the java.policy or server.policy file. Specify JAAS Principal in a JAAS policy file that is specified by the JVM system property java.security.auth.policy or statically set this keyword in the java.security file with auth.policy.url.n=[URL].

 

CSIv2 trusted ID list might use the pipe (|) or comma (,) characters for the delimiter when the server ID is the distinguished name

The CSIv2 trusted ID list might use the pipe (|) or comma (,) characters for the delimiter when the server ID is the distinguished name (DN).

The previous CSIv2 trusted ID list used a comma delimiter before the DN was supported as a server ID. Now that DN is supported as a server ID, the comma is no longer valid to use a delimiter of DNs.

Use the pipe (|) character as the list delimiter from now on. WAS is still supporting the comma (,) character as the list delimiter for backwards compatibility. WAS checks the comma character when the pipe character fails to find a valid trusted ID.

 

Interoperability issue exists between WAS for z/OS and WAS distributed packages when SSL is supported, but not required

An interoperability issue exists between WAS for z/OS and WAS distributed packages when Secure Sockets Layer is supported, but not required.

WAS distributed packages set an integrity required flag for the CSIv2 inbound configuration to true by default because SSL requires integrity at a minimum. However, WAS for z/OS interprets this flag as an SSL requirement.

In the security.xml file for WAS distributed packages system, change the following line from 

 <CSI xmi:id="IIOPSecurityProtocol_1066667906706">
    <claims xmi:type="orb.securityprotocol:CommonSecureInterop" xmi:id="CommonSecureInterop_1066667906706" stateful="true">
         ...
        <requiredQOP xmi:type="orb.securityprotocol:TransportQOP" xmi:id="TransportQOP_1066667906706" establishTrustInClient="false" enableProtection="false" confidentiality="false" integrity="true"/>
         ...
    </claims>

to 

  <CSI xmi:id="IIOPSecurityProtocol_1066667906706">
    <claims xmi:type="orb.securityprotocol:CommonSecureInterop" xmi:id="CommonSecureInterop_1066667906706" stateful="true">
         ...
        <requiredQOP xmi:type="orb.securityprotocol:TransportQOP" xmi:id="TransportQOP_1066667906706" establishTrustInClient="false" enableProtection="false" confidentiality="false" integrity="false"/>
         ...
    </claims>

You also can make the previous change using the WAS administrative scripting commands.

 

A LDAP token gets a new expiration period when validated downstream

A LDAP (LTPA) token gets a new expiration period when validated downstream.

When an LTPA token is sent downstream as the authentication information, a new timestamp is added to the validated LTPA token. This effectively increases the timeout period of the token.

When an interim fix becomes available, you can download this update by accessing the WAS support Web site and clicking All Updates (Fixes, patches, etc.).

 

Configuring the trusted mode to determine if administrators can trust private HTTP headers or not

WAS has tightened security further by introducing a configuration option that permits administrators to specify if they trust private HTTP headers or not.

You must carefully evaluate enabling the WAS Internal HTTP Transport in the trusted mode in the production environment to determine if sufficient trust is established.

When the trusted mode is enabled, the WAS Internal HTTP Transport supports the assertion of the user identity by adding the client certificate to the HTTP header. The Web server plug-in can use this feature to support client certificate authentication. The HTTP header does not carry verifiable information that WAS can use to determine the server identity that asserts the client certificate. You should establish a secure communication channel with transport level authentication between the Web server plug-in and WAS to avoid HTTP header spoofing.

You can configure the trusted mode for each HTTP port independently and disable on any port that client machines can access directly, both from the Internet and the intranet. Requiring the Web server plug-in to establish a SSL connection with client certificate authentication is a way to ensure that only a trusted Web server plug-in asserts the user certificate. Moreover, use a self-signed certificate so that only those servers that have the self-signed certificate can establish a secure connection to the trusted Internal HTTP Transport.

Other than SSL, you can use mechanisms such as VPN and IPSec to protect the Internal HTTP Transport from being accessed by unauthorized users.

The trusted mode is set to true by default. Perform the following steps to add a custom transport property to disable the trusted mode:

  1. Using the console, click Servers > Application Servers > <server name> > Web Container >HTTP Transports > < host> > Custom Properties.

  2. Click New and enter the property name Trusted with the value of false.

  3. Restart the server.

  4. After the server restarts, the transports for which you set Trusted to false do not accept client certificate assertion and return an HTTP Error 403 with the error message similar to the following example in your log file 

    Requests through proxies such as the WebSphere webserver plug-in are not permitted to this port.
        The HTTP transport on port 9080 is not configured to be trusted.

 

Tivoli Access Manager Documentation

To instructions on how to configure Tivoli Access Manager check out:

http://publib.boulder.ibm.com/tividd/td/tdprodlist.html

 

Hardware cryptographic token devices fail on Solaris

Hardware cryptographic token devices do not work properly on the Solaris Operating Environment.

Because of a Java compatibility test problem found in the IBMPKCS11 provider, first locate the IBMPKCS11 provider java.security file by default. If you need to use hardware cryptographic devices, delete the line including...

com.ibm.crypto.pkcs11.provider.IBMPKCS11
...from...

${WAS_INSTALL_ROOT}/java/jre/lib/security/java.security.

The problem in the IBMPKCS11.JAR provider, which makes the deletion of the line necessary, is not significant. It reports the availability of algorithm MD4 that is not present in the IBMPKCS11 provider. This causes a Java compatibility test to fail on the Solaris Operating Environment with the provider enabled.

To get the hardware cryptographic support, delete the IBMPKCS11 provider from...

${WAS_INSTALL_ROOT}/java/jre/lib/security/java.security file.

 

Cannot install an EAR file remotely using wsadmin.sh

The installation of an EAR file to a remote WAS is not a supported operation in wsadmin.sh.

To work around this problem, use the WAS console to install an application whose EAR file resides in a different machine from that of the WAS. An alternative is to include WAS as part of the Network Deployment environment and then use the remote scripting client to install the application to the Deployment Manager.

 

Performance data and tools

 

 

ESIEnable

For performance purposes, edit the plugin-cfg.xml file and change the value of the ESIEnable variable, if it exists, from false to true.

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

 

The prepared statement recommendation might be too large

The TPV Advisor or the Runtime Performance Advisor (RPA) issues advice telling you to increase the size of the prepared statement cache to an unreasonably large value, for example, 3000. On some systems this can cause a system crash or out of memory error.

If the application has a very large number of prepared statements that are all consistently used, there are a lot of discards from the cache. The advisors see the number of discards from the cache and recommend increasing the size of the prepared statement cache. The advisors do not currently take into account the memory resources used by the prepared statement cache entries.

You should not increase the prepared statement cache above 1000 unless you are sure that you have appropriate resources.

 

Contradictory advice on shared resources

The TPV Advisor and the Runtime Performance Advisor (RPA) might give contradictory advice for JDBC (JDBC) Resources configured at the node or cell level and used at the server level.

When servers share a resource, each server might use the resource differently. The advisors only provide advice within the scope of a single server, without consideration of how other servers might be using the shared resource.

You should compare advice about the shared JDBC resources from all the appservers before taking such advice. If the advice is consistent, take it. If the advice is inconsistent, you should use your best judgment to configure the shared resources.

 

TPV cannot connect to a running server if security is enabled

Tivoli Performance Viewer (TPV) cannot connect to a running WAS . The SystemOut.log file of the server located at the $WAS_HOME/logs/<servername> directory might display errors similar to the following

SECJ0305I: Role based authorization check failed for security name <null>, accessId no_cred_no_access_id while invoking method.

If security is enabled in WAS v5, TPV cannot connect to the server using a SOAP connector if the proper user login and password are not set in the SOAP properties file.

Set the user name and password in the soap.client.props file located at the $WAS_HOME/properties directory. You should set the values for the keys com.ibm.SOAP.loginUserid and com.ibm.SOAP.loginPassword. The password can be encrypted using the PropFilePasswordEncoder utility located in $WAS_HOME/bin. You can find more information by searching the topic, "Running your monitoring applications with security enabled" in the WAS v5 information center.

 

TPV cannot set all PMI levels to None

When trying to set the monitoring level for a PMI module to None through TPV, you can find that the monitoring level for the module continually reverts back to High.

If the Runtime Performance Advisor is enabled on the server, it sets the monitoring level for PMI modules back to High. This behavior is by design, because the RPA requires data for certain modules.

 

PMI on AIX

On an AIX platform when the PMI is enabled the following nodeagent SystemOut.log message repeats continuously 

No PMI Module found for the Mbean systemModule

To avoid receiving the message, install the bos.perf fileset.

 

HP memory usage

Using tools on the HP platform to check the memory usage of the WAS process might show a high memory usage (with the maximum set to 256 MB). The virtual number shown in glance and other tools does not represent the actual physical memory committed in use. This is normal behavior on the HP platform.

 

Platform-specific tips for installing and migrating

 

 

Contents

  1. All platforms
  2. All Linux and UNIX-based platforms
  3. AIX platforms
  4. HP-UX platforms
  5. Linux platforms
  6. Solaris Operating Environment

See also

  1. Tips for installing the embedded messaging feature.
  2. Configuring the IBM HTTP Server the Web server plug-in for SSL
  3. WASPreUpgrade command
  4. WASPostUpgrade command
  5. Tips for installing the embedded messaging feature
  6. Installation: Resources for learning

 

All platforms

 

All Linux and UNIX-based platforms

 

AIX platforms

 

HP-UX platforms

 

Linux platforms

 

Solaris Operating Environment

 

Uninstalling applications using wsadmin.sh

  1. Invoke the AdminApp object commands interactively, in a script, or use the wsadmin -c command from an operating system command prompt.

  2. Issue the following command...

    Using Jacl 

    $AdminApp uninstall application1

    Using Jython 

    AdminApp.uninstall('application1')
    where...

    $ is a Jacl operator for substituting a variable name with its value
    AdminApp is an object supporting application objects management
    uninstall is an AdminApp command
    application1 is the name of the application to uninstall

    Note that Specify the name of the application you want to uninstall, not the name of the Enterprise ARchive (EAR) file.

  3. Save the configuration changes with the following command...

    Using Jacl 

    $AdminConfig save

    Using Jython 

    AdminConfig.save()
    Use the reset command of the AdminConfig object to undo changes that you made to your workspace since your last save.

Uninstalling an application removes it from the WebSphere Application Server configuration and from all the servers that the application was installed on. The application binaries (EAR file contents) are deleted from the installation directory. This occurs when the configuration is saved for single server WebSphere Application Server editions or when the configuration changes are synchronized from deployment manager to the individual nodes for network deployment configurations.