Using the latest Jython with a WebSphere Application Server wsadmin thin client
This article explains how you can set up a wsadmin thin client in IBM® WebSphere® Application Server to use the latest release of Jython. Using the latest release of Jython provides the opportunity for you to leverage new language features added since Jython 2.1, such as:
- Try-except-finally code blocks where exceptions need to be handled.
- The with construct for conveniently working with connections and locks.
- Improvements in various libraries; the threading library in particular.
- Performance improvements built into the latest Jython runtime.
Included with this set of instructions are samples of some artifacts that are needed to run the thin client:
- Wrapper script for Windows®, called thinClient.bat, that is used to invoke wsadmin in the thin client.
- Wrapper script for Linux® and AIX®, called thinClient.sh, that is used to invoke wsadmin in the thin client. (This is a bash shell script.) This script is named thinClient.sh to distinguish it from wsadmin.sh that could be used to launch wsadmin from a server profile.
- A wsadmin.properties file configured to work with the thin client.
- Profile script for wsadmin, called ThinClientProfile.py, that is provided with the –profile option for wsadmin. This profile is required to set up the Admin objects correctly and to properly load library modules when the script library option wsadmin.jython.libraries is used.
- A bash script called addAdminObjectImport.sh that modifies the WebSphere Application Server Jython library admin modules to include an import statement for the Admin objects (AdminConfig, AdminControl, AdminTask, and so on) that are used by the module. This script makes it easy to set up the WebSphere Application Server Jython script library to be used with a version of Jython that is different than the one that comes with the WebSphere Application Server installation. (If you are familiar with Windows scripting, you will likely be able to create a comparable script for Windows.)
At the time this writing, the latest release was Jython 2.5.2, but the steps described here should be equally applicable to any newer release. See Related topics for a comprehensive list of features new to Jython 2.5.
The steps described here were tested on Linux®, AIX®, and Windows® using thin clients derived from WebSphere Application Server V7, V8, and V8.5 environments.
Creating the wsadmin thin client environment
General instructions for creating a wsadmin thin client environment are available in the WebSphere Application Server Information Center. The steps listed below are based on the Information Center instructions, but contain minor modifications that specifically address using a different version of Jython.
Below are naming conventions used throughout this article to help make this information easier to understand:
- <PROFILE_HOME> refers to the root directory of a WebSphere Application Server profile from which certain files are copied to create the thin client run time environment. (During the testing of this information, items were copied from a deployment manager profile, but you could use a node profile instead.)
- <WAS_HOME> refers to the root directory of a full WebSphere Application Server installation that is used to copy certain artifacts into the thin client run time environment.
- <THIN_CLIENT_HOME> is used to refer to the root directory of the thin client run time environment.
To create the wsadmin thin client environment:
- Create a top level directory where the thin client environment will be located. In this example, the top level directory is /opt/IBM/WebSphere/ThinClient, although you can put the directory anywhere. (On a Windows machine, do not put the thin client directory in the Program Files path due to the space character in the path name, which can be an annoyance at times.) The top level directory where the thin client is located is referred to generically in these instructions as <THIN_CLIENT_HOME>.
- From an existing WebSphere Application Server environment, copy Java over to <THIN_CLIENT_HOME> by either:
cp –Rto copy <WAS_HOME>/java.
- Using the old-school approach of using
tar –cvfto create an archive of <WAS_HOME>/java. Copy the archive to <THIN_CLIENT_HOME> and extract it with
- In a Windows environment, copy the <WAS_HOME>/java folder to <THIN_CLIENT_HOME>, either by dragging and dropping, or by creating a compressed (.zip) archive, followed by a copy and extraction of the archive.
- Create a directory named lib in <THIN_CLIENT_HOME>. This is where the latest Jython will be installed.
- Copy the jython_installer-2.5.2.jar to <THIN_CLIENT_HOME>.
- Install the latest Jython into the <THIN_CLIENT_HOME>/lib directory.
You will find complete instructions for installing Jython on the Jython
site. When installing Jython, be sure to:
- Use this command to kick off the installer:
java -jar jython_installer-2.5.2.jar
- Use the default standard installation.
- Specify this directory when you are prompted for the location in which to install Jython:
- (Optional, but recommended) Select Other when you are prompted for the path to the Java installation to use with Jython, then navigate to the Java located at <THIN_CLIENT_HOME>/java.
- Use this command to kick off the installer:
- Copy the following JARs to <THIN_CLIENT_HOME>/lib:
- com.ibm.ws.admin.client_#.#.0.jar from <WAS_HOME>/runtimes (where #.# is 7.0, 8.0, or 8.5 depending on the WebSphere Application Server version)
- com.ibm.ws.security.crypto.jar from <WAS_HOME>/plugins
- Create a directory named properties in <THIN_CLIENT_HOME>. This is where some message and configuration files will be located.
- From an existing WebSphere Application Server profile, copy the properties
files listed below from <PROFILE_HOME>/properties to <THIN_CLIENT_HOME>/properties, and make any changes specified:
- ipc.client.props: supports IPC connections.
- soap.client.props: supports SOAP connections.
- Change com.ibm.SOAP.securityEnabled to true.
- sas.client.props: supports JSR160RMI connections (preferred).
- ssl.client.props: supports encrypted connections.
- Change the value of user.root to <THIN_CLIENT_HOME>.
- In this file, use forward slashes in the path to <THIN_CLIENT_HOME>. Java will interpret the path correctly depending on the platform.
- Under the Default self-signed certificate properties section, check that the subject DN (Distinguished Name) is appropriate for your site. (Specifically, you will need to change the organization attribute and, possibly, the country.)
- wsjaas_client.conf: supports secured connections.
- Copy the wsadmin.properties file included with this article into <THIN_CLIENT_HOME>/properties. This sample properties file has already been appropriately configured. Alternatively, you can get a wsadmin.properties file from an existing WebSphere Application Server profile from the <PROFILE_HOME>/properties directory.
- In the wsadmin.properties file, check the parameters listed here to see if you need to adjust their values:
JSR160RMI is the recommended connection type, although in some cases you may find that you need to use the SOAP connection type.
- (optional) com.ibm.ws.scripting.port=0
This is set to a bogus port to avoid accidental connection to a deployment manager.
- (optional) com.ibm.ws.scripting.host=localhost
- (required) com.ibm.ws.scripting.traceFile
Set this value to a path that uses <THIN_CLIENT_HOME>/logs.
- (required) com.ibm.ws.scripting.validationOutput
Likewise, this parameter must also specify a path that uses <THIN_CLIENT_HOME>/logs.
- (optional) com.ibm.ws.scripting.traceString
Default is disabled.
- (optional) com.ibm.ws.scripting.validationLevel
Default is NONE.
-port, and so on.
- (optional) com.ibm.ws.scripting.connectionType=JSR160RMI
- Create a directory named etc in <THIN_CLIENT_HOME>. This is where the thin client key and trust store files will be created for use with encrypted connections to remote deployment managers. (See the ssl.client.props file in the properties directory for configuration details.)
- Copy the sample thinClient.sh or thinClient.bat script provided with this article to <THIN_CLIENT_HOME> and modify it to work with your thin client installation:
- Modify the value of WAS_HOME to include the full path to the directory where you are creating your thin client (which is otherwise referred to as <THIN_CLIENT_HOME>). (In the thinClient.bat script, remember to use back slashes in the path names.)
- Similarly, modify USER_INSTALL_ROOT to the directory where you are creating your thin client (<THIN_CLIENT_HOME>).
- Make sure JAVA_HOME makes sense for the Java you are using. If you are using a Java installed somewhere other than <THIN_CLIENT_HOME>/java, then you will need to update the value of JAVA_HOME accordingly.
- (Optional) Modify wsadminHost to be the default host for the
deployment manager you want to connect to. (You can provide the
–hostargument on the command line when you launch the thin client and that will override the value provided in the wrapper script.) If you wish, you can provide a bogus hostname to avoid accidentally connecting to some WebSphere Application Server process.
- (Optional) Uncomment the wsadminConnType that you want
to be the default connection type. In general, it is
strongly recommended that this be JSR160RMI. This can
be overridden by using the
–conntypeargument when launching the thin client.
- (Optional) Modify wsadminPort to be the default port for
the JSR160RMI connection for the default deployment
manager. (The default JSR160RMI port for deployment managers is 9809, which is the same as the “bootstrap” port.) This can be overridden with the
–portargument when launching the thin client. If you wish, you can provide a bogus port number to avoid accidentally connecting to some WebSphere Application Server process.
- In the script line that sets up the classpath (search for
"client_"), modify the name of the
com.ibm.ws.admin.client_#.#.0.jarto reflect the version of WebSphere Application Server you are using; that is, replace #.# with 7.0, 8.0 or 8.5.
- Create a logs directory in <THIN_CLIENT_HOME>. Make it writable by all. This directory is used for trace files when wsadmin tracing is enabled.
- Create a directory named profiles in <THIN_CLIENT_HOME>. Copy the ThinClientProfile.py file into this directory. This profiles directory is a convenient place to keep a copy of the ThinClientProfile.py file, which does a couple of important things:
- It loads the Admin objects into sys.modules so they are visible to your modules, making import statements for these objects resolve properly.
- It will properly set up sys.path with any library
directories that have Jython modules in them when
libraries are specified with the wsadmin.jython.libraries
Java option. When libraries are to be used, the
thinClient command line will include the -javaoption as
where <path_to_library>is the path to the root directory where the Jython library is located in the file system.
- In ThinClientProfile.py, search for WebSphereVersion and modify the value to 7.0, 8.0, or 8.5 depending on which version of WebSphere Application Server you are using.
- (Optional) For convenience, put <THIN_CLIENT_HOME> in your path. This will enable the thinClient wrapper script to be executed without using its full path.
- (Optional) If you use the wsadmin script libraries (written in Jython)
that come with WebSphere Application Server, then:
- Create an archive of the scriptLibraries directory in an
existing WebSphere Application Server installation. On UNIX
machines this is done with the tar command:
tar –cvf scriptLibraries.tar scriptLibraries
- Copy the scriptLibraries archive to <THIN_CLIENT_HOME>.
- Extract the scriptLibraries archive. On UNIX machines this is done with the tar command:
tar –xvf scriptLibraries.tar
- In order for these libraries to be loaded properly with the thin client using the newer Jython, the root directory name of the libraries needs to be changed to something other than scriptLibraries. In this example, the directory is renamed to wasScriptLibraries.
- Make sure all the class files are deleted so they get
recompiled with the new Jython. From the
find ./wasScriptLibraries –name “*.class” | xargs rm
- You also need to go through all the script library modules and modify them to include an import statement that imports any of the Admin objects used by that module. The import statement is needed to avoid name errors on the Admin objects when the script library modules are used. For UNIX machines there is a bash script that adds the proper import statement to all of the Admin modules in the WebSphere Application Server Jython library. See sample script addAdminObjectImport.sh in the download materials (this script was tested on a Linux platform).
- When launching thinClient.sh use the following option:
where <THIN_CLIENT_HOME> is the root directory of your thin client installation. You may use the same option with a path to other in-house script libraries that you may be accustomed to using
–javaoption “-Dwsadmin.jython.libraries= <THIN_CLIENT_HOME>/wasScriptLibraries”
- Use the –profile option with a path to the
ThinClientProfile.py when launching thinClient.sh in order to
properly construct sys.path with libraries specified by
wsadmin.jython.libraries. For example:
where <THIN_CLIENT_HOME> is the root directory to your thin client installation.
- Create an archive of the scriptLibraries directory in an existing WebSphere Application Server installation. On UNIX machines this is done with the tar command:
- On UNIX platforms, you will likely want to change the ownership of the
<THIN_CLIENT_HOME> directory tree to the user and group that makes
sense for the wsadmin thin client machine. The
chowncommand with the
-Roption can be used to change the user and group ownership for the entire directory tree.
That completes the initial setup. You can now launch the thin client using the thinClient wrapper appropriate for your platform.
Invoking the thinClient
This article assumes that wsadmin.properties has the default language set to jython and conntype set to JSR160RMI or SOAP. When that is the case, the only two arguments needed are a port and a host. You can also set up the port and host in wsadmin.properties to provide a default, but that is not recommend because it can lead to unintended connection to a deployment manager.
Assuming a JSR160RMI default connection type, invoking the thin client on Windows (without running a Jython script) looks like this:
thinClient.bat –port 9809 –host mydmgrhost
Likewise, the minimum command line for invoking the thin client on Linux looks like this:
thinClient.sh –port 9809 –host mydmgrhost
The above command examples will get you into a wsadmin “listener” connected to a deployment manager. (Of course, you will need to provide a valid port number and host name for your environment.)
When you run a script, you can use all the same options (-f, -profile) that you use for wsadmin, as well as any arguments that are intended for your script.
On Windows, be sure to use forward slashes in any path names that you provide to thinClient.bat to enable Java to work properly. If you must use back slashes, you’ll have to use double back slashes.
Running thinClient the first time
The first time you run the wsadmin thin client, Jython will populate its cachedir with class objects that it uses on later startups. Jython will create a temp/cachedir directory in <THIN_CLIENT_HOME> for this object cache. You will see messages for every JAR that gets processed.
The first time you connect to a remote deployment manager, a key and trust store will be created. You will be prompted to add a public certificate from the deployment manager into your thin client trust store. The certificate properties will be displayed for your examination. The first time you use the wsadmin thin client to connect to a different deployment manager, you will be prompted again to add a public certificate for that deployment manager. See the ssl.client.props file for the characteristics and location of the key and trust store. (The key and trust store are created in <THIN_CLIENT_HOME>/etc if you stick with the default configuration.)
In case you encounter any difficulties in your testing, here are some troubleshooting tips:
- Check JAVA_HOME in thinClient.bat or thinClient.sh
If JAVA_HOME is not set properly, and there is no java.exe at the expected location, then the thinClient.bat or thinClient.sh script will not start correctly. On Windows, if the java.exe isn’t correct when launching thinClient.bat from a DOS shell, you will get the message, "The system cannot find the path specified."
- UNIX problems
On UNIX platforms, it is a good idea to run dos2unix on thinClient.sh and ThinClientProfile.py. Odd problems have been cleared up by doing so.
- Use forward slashes in arguments to thinClient.bat
Even on Windows, use forward slashes in the script arguments to thinClient.bat or any Jython scripts you launch via thinClient.bat. If you want to use back slashes you will need to use two together in order for them to be interpreted properly by wsadmin.
- Network visibility of the target host
- You can ping or traceroute from the host where the thin client is running to the host where the deployment manager is running.
- The deployment manager host name resolves correctly. If you are having trouble getting a connection when using the host name, try the raw IP address in its place.
- You are using the correct port of SOAP or JSR160RMI for the target host. You can check the port by looking at the deployment manager ports from the admin console.
- Enabling trace for wsadmin thin client
If you want to turn on trace for launching the thin client, you can modify the traceString attribute in wsadmin.properties. You cannot control trace from the command line.
- Problems with JSR160RMI
If you cannot get JSR160RMI to work, then try SOAP.
- Typos in host name and file paths
Make sure you do not have any typos in the host name or port number for the remote deployment manager that you are trying to connect to. On Windows machines, make sure the drive letter is correct. (It is easy to visually ignore the drive letter when the rest of the path is correct.)
- Problems with SSL configuration
If you don’t have SSL configured properly, then you might see this error:
WASX7023E: Error creating "SOAP" connection to host "localhost"; exception information: com.ibm.websphere.management.exception.ConnectorNotAvailableException: [SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: java.security.InvalidAlgorithmParameter Exception: the trustAnchors parameter must be non-empty; targetException=java.lang.IllegalArgumentException: Error opening socket: javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty]
This is usually caused by misconfiguration of the user.root property in the ssl.client.props file. If the thin client can’t get to where it expects to find the key and trust store, then it won’t be able to create them when it first starts up and it won’t be able to connect to the deployment manager.
Configuring the thin client for use on another machine
Once you have gone through the initial configuration described here, you can zip or tar up the root directory of the thin client and move it to another machine; for example, another administrator’s desktop. To reconfigure the thin client on another machine:
- Unzip or untar the wsadmin thin client in the file system of the machine.
- If the target machine needs a different Java (for example, 32-bit rather than 64-bit), then you need to delete the <THIN_CLIENT_HOME>/java directory and get a Java from a WebSphere Application Server installation of the same architecture as the target machine. Copy that Java into the new <THIN_CLIENT_HOME> directory.
- Modify thinClient.bat or thinClient.sh to make sure the WAS_HOME variable at the top of the file reflects the new installation root of the thin client. (All the other file paths in the script are based on WAS_HOME, so that is the only variable that needs to be changed.)
- In the wsadmin.properties file in <THIN_CLIENT_HOME>/properties, modify the traceFile and validationOutput properties to make sure they are correct for the new thin client home.
- In the <THIN_CLIENT_HOME>/etc directory, delete the key.p12 and trust.p12 store files. These will get recreated for the new host.
- Edit ssl.client.props in <THIN_CLIENT_HOME>/properties to modify the user.root property to reflect the new home of the thin client. This is important in order for the key and trust store to be properly regenerated and used when the thin client is invoked.
- If you are using soap.client.props to provide a user and password, then you might need to modify the user and password to use the identity of the administrator that is going to use this instance of the wsadmin thin client.
After making these changes, your new wsadmin thin client should be ready to run. You can test it by running thinClient.bat or thinClient.sh from a shell.
Moving forward with Jython
As you continue to use the newer version of Jython, there are a few things you will want to keep in mind to make sure your transition and future processing go smooth:
- The newer Jython uses Unicode strings. This will present an issue if you have tests in your wsadmin scripts for string types that use type(“”) . You will need to add an additional test that uses type(u””).
- The newer Jython supports newer language features that are not backward compatible with the Jython that is presently built into WebSphere Application Server. Once you start using these newer language features in your wsadmin scripts, be aware that you won’t be able to run those same scripts in a standard WebSphere Application Server wsadmin environment.
This article provides a way for you to use the latest version of Jython without disturbing your existing WebSphere Application Server installations. By setting up a wsadmin thin client with the latest Jython, you can develop and run wsadmin scripts that take advantage of the latest in Jython language features and improvements.