Moving the installation directory of WebSphere installations

To a Java EE developer who is used to lightweight containers like JBoss, WebSphere seems like a partially more powerful, yet monstrous monolithic block.

One of the strengths of the WebSphere stack is its internal product registry which automatically tracks all installations of application servers, feature packs and fix packs. Whenever you set up a new application server or server profile unused TCP/IP ports are suggested automatically to avoid conflicts with other profiles. However, this registry might turn into a pitfall whenever you want to modify installations manually.

For instance, if you want to move the installation directory of an application sever all you have to do with JBoss is move the installation directory. The same attempt with WebSphere will most likely lead to incorrect server startup, the impossibility to apply fix packs and other "inconveniences".

The product registry is the most obvious hindrance to ease-of-use. After all, I managed to move my WebSphere Process Server 6.1 installation to another directory on a Windows system. The steps described below should be treated as hints for those who plan to do something similiar and not as a complete and definite guide to tampering with WebSphere installations.

1. I started with physically moving the complete installation directory of WebSphere Process Server to the desired destination.
2. Since the WebSphere setup routines enter absolute path descriptions in the shell scripts that reside in the bin directories of the server and its profiles it is advisable to perform a search & replace operation on all files in the new server installation directory. Replace the old absolute path description by the new absolute path description. On Windows systems, it is crucial to perform the operation twice: once with backslashes and once with forward slashes.
3. Open the Windows registry editor (regedit.exe) and navigate to the following path:
   HKEY_CURRENT_USER\Software\IBM
   Expand the the product entry of the moved product, expand it and select the appropriate product version. Alter the path descriptions in the BinPath, InstallLocation and LibPath entries appropriately.
   Note to Linux users: if you use the Red Hat Package Manager, the product might be registered there in a similar manner.
   
4. Move to the Windows directory (most likely C:\WINNT or C:\WINDOWS). You will find a text file called .nifregistry. Replace the old path descriptions in the file by the new ones.
   Note to Linux users: the file should be located under /opt/.ibm/.nif/.nifregistry.
   
5. In the same directory, you will find a file called vpd.properties. Apply the same search & replace operation to it. The last two steps will allow for the IBM Update Installer and the Profile Management Tool being able to pick up the new location of the application server.
6. If your product was installed using the IBM Installation Manager move to your user home directory (e.g. C:\Documents and Settings\All Users\Application Data) and open the IBM\Installation Manager sub directory. Also perform a search & replace on the files contained there and in all sub directories.

I know its a bit of an ordeal - however, it seems to be manageable in the end!

Best regards,
Matthias

"Apply the integration test client update to the server" message in WID 6.1

It is rumored that some people who develop SCA components in WebSphere Integration Developer (WID) also want to test their components. Well, as I admit, I am one of them.

If you are also one of them and if you use WID version 6.1 along with a standalone instance of WebSphere Process Server (WPS) 6.1 then you might have stumbled across a neat error message in the Integration Test Client. It says

Apply the integration test client update to the server.

Moreover, if you then decided to delve further into the wherefores and possible solutions to this kind of problem you might have found fixes for WID versions 6.0.1.2 and 6.0.2.2 on http://www-1.ibm.com/support/docview.wss?rs=2308&context=SSQQFK&q1=4010662&uid=swg24010662

But what about WID and WPS versions 6.1? As it turns out, IBM released a fix for WPS 6.1 on 4/1/2008. Please visit http://www-1.ibm.com/support/docview.wss?rs=2308&uid=swg24017940 to download it. At the time of this writing the page wasn't listed in Google.

You also ought to make sure that you have installed the Interim Fix 001 for WID 6.1 which can be downloaded on http://www-1.ibm.com/support/docview.wss?rs=2308&uid=swg27011454.

Please note that the error message mentioned above does not occur if you use the integrated testing environment that ships with WID 6.1. Only standalone servers are affected - regardless of whether they reside on the same machine as WID or on a remote machine.

Best regards,
Matthias

Having trouble viewing SVG process diagrams in BPC Explorer?

Yesterday I discovered an extremely neat feature of Business Process Explorer: The "view process state" function. It displays a SVG graphics resembling the business process diagram designed in the Websphere Integration Developer. What's more - it also marks the current state of the business process instance. That's useful if you'd like to know where your process hangs (if yours ever hangs indeed...).

However today I encountered some trouble viewing these graphics. Not only the "view process state" function produced errors but also the "view structure" function with process templates. In Firefox, a yellow field occurred saying there was an error in the underlying XML. On the server console, the following error message was visible:

java.security.AccessControlException: Access denied (java.lang.RuntimePermission exitVM)

If you should run into the same trouble, here's one tip: restart your server in 'Run' mode instead of 'debug" mode! Funny but true, the SVG export does not work in debug mode...

Best regards,
Matthias

Switching the Websphere log language

The fact that IBM translated all their log messages into German is actually very nice of them. However, I'm not really pleased with it because you won't find anything on the web when searching for German error messages. Hence, reverting to Englisch messages would be desirable but as it seems there's no switch in the Websphere admin console saying "change log language"...

So here's a kind of brutal but effective approach to change the log language of a Websphere Application Server:

1. In the admin console navigate to your server.
2. In the section "Server Infrastructure", expand the node "Java and Process Management" and click "Process Definition".
3. In the section "Additional Properties", click "Java Virtual Machine".
4. To the "Generic JVM arguments", add the following argument: "-Duser.language=US"

That's it. Restart the server and have fun...
Matthias

Accessing secured EJBs on Websphere 6.1 from a standalone ("thin") client

Trying to access a secured EJB on Websphere can give you a hard time, especially if you want do so in a standalone Java client. It's not just a simple matter of creating an InitalContext with appropriate security credentials and hoping that the server will propagate the security context to the EJB container.

Basically, I wanted to access the HumanTaskManager deployed on a Websphere Process Server 6.1 instance from a standalone Java client in order to simulate task completion without human intervention.

The HumanTaskManager is implemented as a 2.1 Enterprise Java Bean. To access and use it you have to follow the standard procedure outlined below:

1. Create a JNDI InitialContext.
2. Look up the EJB Home.
3. Invoke one of the create() methods on the EJB home to create an instance of the target EJB.
4. Invoke the desired business methods on the previously created EJB instance.
   

Accessing a secured EJB on Websphere is no exception in that respect. In my case, the client application only threw an exception when I wanted to call a business method on the previously created EJB instance (step 4):

java.rmi.AccessException: CORBA NO_PERMISSION 0x0 No; nested exception is:
org.omg.CORBA.NO_PERMISSION:
>> SERVER (id=4773e3aa, host=XXX.highq-it.de) TRACE START:
>> org.omg.CORBA.NO_PERMISSION: java.rmi.AccessException: ; nested exception is:
com.ibm.websphere.csi.CSIAccessException: SECJ0053E: Authentifizierung für /UNAUTHENTICATED beim Aufrufen von (Bean)com/ibm/task/api/HumanTaskManagerHome query(java.lang.String,java.lang.String,java.lang.String,java.lang.Integer,java.util.TimeZone):1 securityName: /UNAUTHENTICATED;accessID: UNAUTHENTICATED is not granted any of the required roles: TaskAPIUser fehlgeschlagen

An odyssee through the depths of the world wide web began before I had finally gathered the information to get the client to work. To make a long story short: You have to write a programmatic login using JAAS and set the authenticated subject as default subject on the current thread. Furthermore, you have to ensure that your program has the correct Java Runtime, i.e. the correct libraries available and is configured appropriately using JVM arguments.

My method that performs the JAAS login looks as follows:

public void login(String userName, String password) throws LoginException, WSSecurityException, NamingException {
InitialContext ctx = getInitialContext(); // standard procedure
ctx.lookup("");

lc = new LoginContext("WSLogin",
new WSCallbackHandlerImpl(userName, password));

lc.login();
subject = lc.getSubject();

WSSubject.setRunAsSubject(subject);
}

The InitialContext can be created in the standard way, using the correct InitialContextFactory (normally com.ibm.websphere.naming.WsnInitialContextFactory) and provider url (in my case corbaloc:iiop:localhost:2809).
The default lookup ctx.lookup("") is performed so that the target security realm and bootstrap host/port is determined automatically for SecurityServer lookup (see example in http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/topic/com.ibm.websphere.base.doc/info/aes/ae/tsec_pacs.html).

The line WSSubject.setRunAsSubject(subject); sets the previously authenticated subject as the J2EE "run as" identitity on the current thread meaning that all subsequent J2EE calls in the same thread will use this subject for authorization checks.

To get the login process to work, I also included the libraries of the target server runtime in the classpath of the Java program. For more information on how to include only client-specific libraries, please use the above URL as a starting point. Since I am using the Websphere Integration Developer, the easiest way to ensure the correct runtime environment was to add the System JRE of the Websphere Process Server on which the target EJB is running.

Furthermore, the following JVM args had to be added to the program:
-Djava.security.auth.login.config=\pf\wps\properties\wsjaas_client.conf -Dcom.ibm.CORBA.ConfigURL=file:\pf\wps\properties\sas.client.props

This is to pass the information of the used login and SSL/CSI configuration to the program. See http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/tips0221.html?Open and http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/topic/com.ibm.websphere.base.doc/info/aes/ae/tsec_j2clogin.html for more information on this.

At this point, I encountered another exception which made me getting a bit frustrated in the end:
Forwarded IOR failed with: CAUGHT_EXCEPTION_WHILE_CONFIGURING_SSL_CLIENT_SOCKET Exception=com.ibm.websphere.ssl.SSLException: Missing SSL client config properties.

Finally, a note on http://www-1.ibm.com/support/docview.wss?uid=swg21238509 made me feel easy. In Websphere 6.1, it is also necessary to pass the location of a file called ssl.client.props to the JVM:
-Dcom.ibm.SSL.ConfigURL=file:pf\wps\properties\ssl.client.props

Hope this helps...
Matthias

PS: Yet another helpful piece of information: In the IBM techdocs, a standlalone Java client is refererred to as "thin client".