Websphere thin client

WebSphere Application Server comes with wsadmin tool for scripting application serving environment. Nevertheless, to use wsadmin we don’t have to install full WAS, just a couple of JAR files is enough, as IBM offers Administration Thin Client .

Files preparation

• JRE 5+ : only IBM’s JDK is officially supported, so you may use the bundled JDK in WAS installation, or download the standalone JDK from IBM’s site and install:
  https://www.ibm.com/developerworks/java/jdk/

• Client JARs :
  + create thinClient directory: /opt/IBM/wasThinClient (or C:\Program Files\IBM\wasThinClient)
  + Copy com.ibm.ws.admin.client_VERSION.jar from WAS_HOME/runtimes to wasThinClient dir.
  + Depending on the version, you may need to copy more jars to wasThinClient dir: com.ibm.ws.security.crypto_VERSION.jar(WAS_HOME/plugins), com.ibm.ws.webservices.thinclient_VERSION.jar (WAS_HOME/runtimes)

• Config files:
  + create properties directory in wasThinClient dir.
  + copy soap.client.props, ssl.client.props in WAS_HOME/profiles/PROFILE/properties to wasThinClient/properties dir
  + You may copy sas.client.props and wsadmin.properties in that folder also; but sas.client.props is not needed if you are using soap, and the wsadmin default properties can be overriden via command-line arguments.
  + create etc directory in wasThinClient dir, copy trust.p12 (and optionally key.p12) from WAS_HOME/AppServer/profiles/profileName/etc to it.

Files customization

+ Edit ssl.client.props
See http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/topic/com.ibm.websphere.express.doc/info/exp/ae/rsec_sslclientpropsfile.html

+ Edit soap.client.props
See http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.express.doc/info/exp/ae/csec_sslsecinstallclientsignret.html

+ Edit wsadmin.sh (or wsadmin.bat)
Example wsadmin.sh:

#!/bin/bash
# example wsadmin launcher
# WAS_HOME should point to the directory for the thin client

WAS_HOME="/MyThinClient"
USER_INSTALL_ROOT="/MyThinClient"

# JAVA_HOME should point to where java is installed for the thin client
JAVA_HOME="$WAS_HOME/java"

WAS_LOGGING="-Djava.util.logging.manager=com.ibm.ws.bootstrap.WsLogManager -Djava.util.logging.configureByServer=true"

if [[ -f ${JAVA_HOME}/bin/java ]]; then
   JAVA_EXE="${JAVA_HOME}/bin/java"
else
   JAVA_EXE="${JAVA_HOME}/jre/bin/java"
fi

# For debugging the utility itself
# WAS_DEBUG=-Djava.compiler="NONE -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=7777"

CLIENTSOAP="-Dcom.ibm.SOAP.ConfigURL=file:${USER_INSTALL_ROOT}/properties/soap.client.props"
CLIENTSAS="-Dcom.ibm.CORBA.ConfigURL=file:${USER_INSTALL_ROOT}/properties/sas.client.props"
CLIENTSSL="-Dcom.ibm.SSL.ConfigURL=file:${USER_INSTALL_ROOT}/properties/ssl.client.props"
CLIENTIPC="-Dcom.ibm.IPC.ConfigURL=file:${USER_INSTALL_ROOT}/properties/ipc.client.props"

# the following are wsadmin property 
# you need to change the value to enabled to turn on trace
wsadminTraceString=-Dcom.ibm.ws.scripting.traceString=com.ibm.*=all=enabled
wsadminTraceFile=-Dcom.ibm.ws.scripting.traceFile=${USER_INSTALL_ROOT}/logs/wsadmin.traceout
wsadminValOut=-Dcom.ibm.ws.scripting.validationOutput=${USER_INSTALL_ROOT}/logs/wsadmin.valout

# this will be the server host that you will be connecting to
wsadminHost=-Dcom.ibm.ws.scripting.host=myhost.austin.ibm.com

# you need to make sure the port number is the server SOAP port number you want to connect to, in this example the server SOAP port is 8875
wsadminConnType=-Dcom.ibm.ws.scripting.connectionType=SOAP
wsadminPort=-Dcom.ibm.ws.scripting.port=8875

# you need to make sure the port number is the server RMI port number you want to connect to, in this example the server RMI port is 2811
#wsadminConnType=-Dcom.ibm.ws.scripting.connectionType=RMI
#wsadminPort=-Dcom.ibm.ws.scripting.port=2811

# you need to make sure the port number is the server JSR160RMI port number you want to connect to, in this example the server JSR160RMI port is 2811
#wsadminConnType=-Dcom.ibm.ws.scripting.connectionType=JSR160RMI
#wsadminPort=-Dcom.ibm.ws.scripting.port=2811

# you need to make sure the port number is the server IPC port number you want to connect to, in this example the server IPC port is 9630
#wsadminHost=-Dcom.ibm.ws.scripting.ipchost=localhost
#wsadminConnType=-Dcom.ibm.ws.scripting.connectionType=IPC
#wsadminPort=-Dcom.ibm.ws.scripting.port=9630

# specify what language you want to use with wsadmin
wsadminLang=-Dcom.ibm.ws.scripting.defaultLang=jacl
#wsadminLang=-Dcom.ibm.ws.scripting.defaultLang=jython

SHELL=com.ibm.ws.scripting.WasxShell

# If wsadmin properties is set, use it
if [[ -n "${WSADMIN_PROPERTIES+V}" ]]; then
     WSADMIN_PROPERTIES_PROP="-Dcom.ibm.ws.scripting.wsadminprops=${WSADMIN_PROPERTIES}"
else
     # Not set, do not use it
     WSADMIN_PROPERTIES_PROP=
fi

# If config consistency check is set, use it
if [[ -n "${CONFIG_CONSISTENCY_CHECK+V}" ]]; then
     WORKSPACE_PROPERTIES="-Dconfig_consistency_check=${CONFIG_CONSISTENCY_CHECK}"
else
     WORKSPACE_PROPERTIES=
fi

# Parse the input arguments
isJavaOption=false
nonJavaOptionCount=1
for option in "$@" ; do
  if [ "$option" = "-javaoption" ] ; then
     isJavaOption=true
  else
     if [ "$isJavaOption" = "true" ] ; then
        javaOption="$javaOption $option"
        isJavaOption=false
     else
        nonJavaOption[$nonJavaOptionCount]="$option"
        nonJavaOptionCount=$((nonJavaOptionCount+1))
     fi
  fi
done

DELIM=" "
C_PATH="${WAS_HOME}/properties:${WAS_HOME}/com.ibm.ws.admin.client_7.0.0.jar:${WAS_HOME}/com.ibm.ws.security.crypto.jar"

#Platform specific args...
PLATFORM=`/bin/uname`
case $PLATFORM in
  AIX® | Linux® | SunOS | HP-UX)
    CONSOLE_ENCODING=-Dws.output.encoding=console ;;
  OS/390®)
    CONSOLE_ENCODING=-Dfile.encoding=ISO8859-1
    EXTRA_X_ARGS="-Xnoargsconversion" ;;
esac

# Set java options for performance
PLATFORM=`/bin/uname`
case $PLATFORM in
  AIX)
      PERF_JVM_OPTIONS="-Xms256m -Xmx256m -Xquickstart" ;;
  Linux)
      PERF_JVM_OPTIONS="-Xms256m -Xmx256m -Xj9 -Xquickstart" ;;
  SunOS)
      PERF_JVM_OPTIONS="-Xms256m -Xmx256m -XX:PermSize=40m" ;;
  HP-UX)
      PERF_JVM_OPTIONS="-Xms256m -Xmx256m -XX:PermSize=40m" ;;
  OS/390)
      PERF_JVM_OPTIONS="-Xms256m -Xmx256m" ;;
esac 

if [[ -z "${JAASSOAP}" ]]; then
     JAASSOAP="-Djaassoap=off"
fi

"${JAVA_EXE}" \
    ${PERFJAVAOPTION} \
    ${EXTRA_X_ARGS} \
    -Dws.ext.dirs="$WAS_EXT_DIRS" \
    ${EXTRA_D_ARGS} \
    ${WAS_LOGGING} \
    ${javaoption} \
    ${CONSOLE_ENCODING} \
    ${WAS_DEBUG} \
    "${CLIENTSOAP}" \
    "${JAASSOAP}" \
    "${CLIENTSAS}" \
    "${CLIENTSSL}" \
    "${CLIENTIPC}" \
    ${WSADMIN_PROPERTIES_PROP} \
    ${WORKSPACE_PROPERTIES} \
    "-Duser.install.root=${USER_INSTALL_ROOT}" \
    "-Dwas.install.root=${WAS_HOME}" \
    "-Dcom.ibm.websphere.thinclient=true" \

    ${wsadminTraceFile} \
    ${wsadminTraceString} \
    ${wsadminValOut} \
    ${wsadminHost} \
    ${wsadminConnType} \
    ${wsadminPort} \
    ${wsadminLang} \
    -classpath \
    "${C_PATH}" \
    com.ibm.ws.scripting.WasxShell \
    "${nonJavaOption[@]}"

exit $?

Launching

Basic launching :
./wsadmin.sh -lang jython -user wasadmin -password secret -host localhost -c ‘print 1+1’

Launching deployment using the “deployOnWas.py” script :
./wsadmin.sh -lang jython -user wasadmin -password secret -host 192.168.1.100 -port 8880 -f deployOnWas.py my-killer-app-2.2.75.war killerapp

To avoid passing plain password to shell command, modify the value of key com.ibm.SOAP.loginPassword in “properties/soaps.client.props” to provide SOAP default password :
com.ibm.SOAP.loginPassword=secret

Likewise, we can provide a default username for the authentication:
com.ibm.SOAP.loginUserid=wasadmin

Troubleshooting

Message:

WASX7017E: Exception received while running file "deployOnWas.py"; exception information: com.ibm.websphere.management.filetransfer.client.TransferFailedException
java.net.UnknownHostException: java.net.UnknownHostException: katavntest01

==> Fix: edit hosts file to map hostname to IP address

Message:

WASX7023E: Error creating "SOAP" connection to host "192.168.1.232"; exception information: com.ibm.websphere.management.exception.ConnectorNotAvailableException: [SOAPException: faultCode=SOAP-ENV:Protocol; msg=; targetException=java.net.MalformedURLException]

==> Fix: make sure the server is running at given host IP and allowing SOAP at that Port (default 8880 or 8879).
Message:

WASX7017E: Exception received while running file "deployOnWas.py"; exception information: com.ibm.websphere.management.exception.ConnectorException 
org.apache.soap.SOAPException: [SOAPException: faultCode=SOAP-ENV:Client; msg=Read timed out; targetException=java.net.SocketTimeoutException: Read timed out]

==> Fix: increase timeout limit in “soap.client.props” file from 180s to at least 3000s
com.ibm.SOAP.requestTimeout=4000
Message:

WASX7017E: Exception received while running file "deployOnWas.py"; exception information: com.ibm.websphere.management.filetransfer.client.TransferFailedException
java.net.ConnectException: java.net.ConnectException: Connection refused

==> Fix: edit hosts file to map hostname to IP address

Message:

WASX7023E: Error creating "SOAP" connection to host "192.168.100.110"; exception information: com.ibm.websphere.management.exception.ConnectorNotAvailableException: [SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: java.net.SocketException: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory; targetException=java.lang.IllegalArgumentException: Error opening socket: java.net.SocketException: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory]

==> Fix: add IBM’s crypto.jar (com.ibm.ws.security.crypto_VERSION.jar) to classpath
Message:

WASX7023E: Error creating "SOAP" connection to host "192.168.100.230"; exception information: java.lang.NoClassDefFoundError: org.osgi.service.url.AbstractURLStreamHandlerService

==> Fix: add org.eclipse.osgi_3.2.1.R32x_v20060919.jar to classpath , or use the upgraded admin Jar in fixed versions.

./.

UPDATE 2019

The script deployOnWas.py I did not store then. Now I put a simple version here:

https://bitbucket.org/ducquoc/jutil-dq/src/master/snippets-dq/deployOnWas.py

Mirror : https://gitlab.com/ducquoc/jutil-dq/blob/master/snippets-dq/deployOnWas.py

Simple EAR file for testing: http://www.mediafire.com/file/7mnlggzobmbh7ld/war.ear/file (mirror: https://gitlab.com/dq-pub-store/dq-pub-files/blob/master/sparse-checkout-ductest/EXPORTED/war.ear )

UPDATE 2020

The steps in the original articles are mostly automated now, there are several open source projects do that. Therefore, instead of some manual steps like above, we can just get some project in BitBucket/GitLab and build to retrieve the Websphere thin client.

Example binary built:

http://www.mediafire.com/file/lvp38rcvog0rqa4/websphere-thin-client-9.0.5.1.zip/file

(old - without Jython: http://www.mediafire.com/file/jx4um058ufq1bhq/websphere-thin-client-9.0.5.1-thin-client.zip/file )

(after extraction – /opt/websphere-thin-client or C:\opt\websphere-thin-client – that can be used as WAS_HOME for wsadmin operations)

Example GitHub project: (homework)

./.