Wsadminlib now available at github.com!

IBM has publicly released wsadminlib at github.com:

https://github.com/wsadminlib/wsadminlib

Github is a popular modern file-sharing service.  Github allows you to use their service for free when you share your contributions publicly.  This is the same as our goal for wsadminlib, so it's a perfect match.

To report problems, ask questions, or make suggestions, please visit: https://github.com/wsadminlib/wsadminlib/issues

Wsadminlib is still available from IBM developerWorks, but it's download-only.  Now that wsadminlib is released at github, you are welcome and encouraged to fork your own branches and share your contributions with other users.

We hope you like it!

PS:  To download a quick zip of the entire package, go to the github site and click the button "Download ZIP" on the lower right.

Fix for bug in method createUsingTemplate()

Here is a fix for a recently-discovered problem which has been hiding in wsadminlib for a long time.

Method createUsingTemplate() calls helper method _create() and passes-in a template.  When the template parameter is non-null, _create() calls AdminConfig.create() with the additional template parameter.  This doesn't work.  It should be calling AdminConfig.createUsingTemplate().

To fix it, edit your copy of wsadminlib, go to helper method _create() and find the section 'if template' (around line 8676, depending on your version).  Change AdminConfig.create() to AdminConfig.createUsingTemplate().  It should look like this:

        if template:
            sop(m, 'AdminConfig.create(%s, %s, %s, %s)' % (repr(type), repr(parent), repr(attrs), repr(template)))
            object=AdminConfig.createUsingTemplate(type, parent, attrs, template)

Many thanks to Yun-Shian Jiang in Canada who reported the problem, debugged it, and suggested the correct fix.

Saving large EAR files

Things have been quiet here at 'wsadminlib central' lately, since many contributors have been focused on getting WAS V8 out the door.  Now that WAS V8 has shipped, here is a brief update...

Frequent wsadminlib contributor Chris in Australia reported a problem saving a large EAR file, on the order of 300 Mb.  He had trouble starting the application immediately after doing a save and sync.  He also observed that the file system was still growing for a short time after the sync.

Now I always thought that an application was fully deployed and ready to start when wsadminlib's method saveAndSync() returned, but not true...

WAS V8 and wsadminlib.py

The IBM WebSphere Application Server version 8.0 was released a few weeks ago, and wsadminlib helped deliver it.  Wsadminlib was used internally within IBM as part of many automated testcases.  This included the original prototypes, all the betas, and the final verifications.

So as you move forward migrating from prior versions of WAS to V8, you may continue using wsadminlib knowing it performed yeoman's service throughout the latest release's development and delivery.

How to enable memory-to-memory session replication for an existing server?

I received this interesting question last week from a wsadminlib user in Chicago.   Wsadminlib.py contains two methods which make the task easy:  createReplicationDomain() and setServerSessionReplication().

First, I connected my wsadmin client to the deployment manager and execfile'd wsadminlib.py:

root@ding6:/home/ding/tmp# /opt/WAS70/profiles/v7default/bin/wsadmin.sh -lang jython -host zwasxxxx.raleigh.ibm.com -port 8879 -user xxxxxx -password xxxxxx
WASX7209I: Connected to process "dmgr" on node WAS00Manager using SOAP connector;  The type of process is: DeploymentManager
WASX7031I: For help, enter: "print Help.help()"
wsadmin>
wsadmin>execfile('wsadminlib.py')
$Id: wsadminlib.py 104 2010-02-15 19:06:18Z ding $
wsadmin>

Presentation on wsadminlib.py

I gave a presentation introducing wsadminlib.py to the WebSphere User Group meeting in Research Triangle Park, NC last week.  You can fetch a PDF copy from the WebSphere User Group site.  [here] from [here]

You can also view the presentation online at slideshare.net, thanks to my teammate and fellow wsadminlib contributor Rohit K.  [here]

Please let us know if you would like a presentation at your local WebSphere User Group meeting, and we will try to find a local contributor.

Beware of mail methods

I have received two problem reports from wsadminlib users about the mail methods in wsadminlib.py. I will post an update after the original authors and users have a chance to investigate.

Sorry for the nuisance.

Fixes for compareIntLists(), etc.

Here are fixes for two problems reported by a user...

The first problem, in method compareIntLists(), is significant. This method is used to determine whether one version of WAS is greater than another. The original method has two tests at the bottom, for greater-than and less-than, and both tests returned the same value of 'negative one'. Not good.

 Unfortunately, this bug has been present for several years. If you are using it to steer config options or to select testcases, beware they might change with this fix.

I rewrote the method to be simpler and more understandable than the original, and I tested it well. A complete replacement appears below the jump...

Updated wsadminlib.py now available

An updated version of wsadminlib.py has been published on IBM developerWorks.

It provides:

• 35 new methods covering a variety of functional areas: applications, security, caching, JVM properties, SIBus, etc.  It also provides several methods to configure the new High Performance Extensible Logging (HPEL) feature available in the WebSphere Application Server V8 (currently in beta).
• 7 updates to existing methods.  These are few small fixes and a few new parameters for existing methods.
• 1 useless method was deleted; it was in the original version by mistake.
• The ability to access methods in wsadminlib.py using the python import statement. 

The full list of method changes is attached below the jump.

The new wsadminlib.py has the same terms and conditions as the original.  To summarize, it is a free. 'as-is', sample script package, not supported by IBM.  The official statement is in the prologue of wsadminlib.py.

This update replaces the original version of wsadminlib.py published in April 2010.  Be sure to save your original copy in case you have modified it or don't like something in the new update.

You may fetch the updated version of wsadminlib from the same location:
- go to [IBM developerWorks WebSphere Sample Scripts]
- search for 'wsadminlib'.

On behalf of the more than 30 contributors, we hope you continue to find wsadminlib.py to be an incredibly useful resource.

PS: The new update contains SVN revision number 115:

        print "$Id: wsadminlib.py 115 2011-01-03 15:51:00Z dingsor $"

A review of wsadminlib.py

I recently happened upon a review of wsadminlib.py written by a fellow IBM employee.

He writes...
        "I recently downloaded the wsadminlib.py script and began constructing WebSphere CloudBurst script packages to utilize it. To say I am impressed would be an understatement. This file makes so many tasks so incredibly simple..."

Click here to read the full review:   [Tools from the experts] 

Thanks Dustin!

IBM Impact 2011

- Are you attending the IBM Impact 2011 conference?
- Do you use wsadminlib?
- Would you like to give a brief presentation with me?

I have proposed a session on wsadminlib to the Impact committee.  I proposed introducing wsadminlib and explaining how to use it.  If the session is accepted, I would like to recruit a wsadminlib user to speak along with me, to give a brief perspective and testimonial.

There are some perks for speakers too.

Please let me know:  dingsor [at] us dot ibm dot com

How to start a Node Agent using scripting?

This is a tricky question.  The quick answer is that it can't be done using the typical wsadmin commands.  But it can be done by 'shelling out' from your python script to issue an operating system command.

My colleague and fellow wsadmin contributor Jose Luis provided this Q&A dialog...


1) Is it possible to start the Node agent using wsadmin scripting?

No.

You can not do any operations on a Node agent if it is down. A Node agent must be running in order to work with it.

2) Why don't wsadminlin.py methods such as 'startServer' and 'isServerRunning' work for Node agents?

The job of the node agent is to start and stop servers, and to monitor them.  Under the covers, the wsadmin startServer command asks a running node agent to start servers.  But the node agent can not start itself.  Therefore the 'startServer' command can not start a node agent.

However, method 'isServerRunning' does work on Node agents. It returns True if the node agent is running and False if it is down.

3) How do I start a Node agent that is not running?

Request for Feedback

Are you using wsadminlib.py?   Does it work well for you?

Would you like an update with some fixes and new methods?

Please send me a note.  I promise to keep your email private, no spam, no sharing.

Thanks

Python 'not callable' errors

Be careful not to heist the names of methods in wsadminlib.py...

The python language allows you to dynamically redefine a method to a variable, and vice-versa. This can be a nice feature if you do it intentionally. But it can be a nuisance to debug if unintentional. Here is a quick example:

First, define a method which returns the sum of two numbers:

ding@dingp:~$ python
Python 2.5.2 (r252:60911, Jan 20 2010, 21:48:48)
[GCC 4.2.4 (Ubuntu 4.2.4-1ubuntu3)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
>>> def myMethod(i,j):
... return i+j
...
>>>

Pass in two numbers, set the return value to another variable, and it works as expected.

>>> k = myMethod(1,2)
>>> print k
3
>>>

But watch what happens next...

How to set custom properties in Global Security?

Use wsadminlib's method setCustomPropertyOnObject().

Here is the method signature. The parameters are straightforward:

setCustomPropertyOnObject(object_id, propname, propvalue)

The pydoc is pretty good too. If a property with this name does not exist, the method creates it. If one already exists, the method sets the new value.

Here is an example:

sid = getObjectsOfType('Security')[0]
setCustomPropertyOnObject(sid,'andy.propkey','andy.propvalue')
save()

We can then browse to the admin console and see the new custom property in the list.

Extra info:  We can also query the value of a custom property with this method.

getObjectCustomProperty(object_id, propname)

How to handle object-like strings?

Several wsadmin commands return 'object-like' strings as responses. That is, they return strings which look like objects, but are just strings. Very annoying.

We wrote several helper methods in wsadminlib.py to convert these object-like strings into real python lists and dictionaries. The helpers may seem silly at first, but having real objects makes searching and extracting values from responses much easier. Here are two examples...

Example 1

Consider this string:

'[ [key0 value0] [key1 value1] [key2 value2] ]'

This is the format of the response string which you get from several wsadmin commands. To a human, it is visually recognizable as a set of keys and values. But to python, it is nothing. It is a string which is tedious to parse and search, and the code is confusing to duplicate inline in various functional methods. What to do?

How to install an application?

Use wsadminlib's method installApplication().

Here is the method signature. The parameter names are straightforward, and the pydoc is pretty good. The list of servers is meant to specify individual non-clustered servers. If a server is part of a cluster, just specify the cluster name.

def installApplication( filename, servers, clusternames, options )

Clusters

First let's install an app on a cluster of servers. Define the name of the ear file, and the name of the cluster. Then install the app, specifying an empty list for individual servers, and no options.

filename = '/tmp/pxyapps.ear'
clusternames = [ 'cluster1' ]
installApplication( filename, [], clusternames, None )

After saving the config, we can browse to the admin console, look at the app's mappings, and see it worked:

Individual servers

Next let's install an app on an individual non-clustered server. Define the server in a list of dictionaries containing the node name and server name. This time we specify an empty list for the clusternames.

How to create a cluster and servers?

Use wsadminlib methods createCluster() and createServerInCluster().

First create a cluster, specifying the cell name and cluster name:

createCluster( 'cell1', 'cluster1')

Then create servers, specifying the cluster name, node name, and server name:

createServerInCluster( 'cluster1', 'node1', 'server1')
createServerInCluster( 'cluster1', 'node1', 'server2')

That was easy. We created one cluster with two servers. This screenshot shows the two servers with the cluster name in the Admin Console.

It's also easy to create a replication domain and enable session replication with these same commands. If you look at the two method signatures in wsadminlib.py, you'll see optional parameters for replication. They are disabled by default, and you can override them as follows:

Who wrote wsadminlib.py?

wsadminlib.py was originally created by two IBM product developers in 2006. They shared it with teammates and it grew into an internal community project with several dozen volunteer contributors thus far.

Click on the thumbnail image to see the list of people who have contributed to the first version published on developerWorks (and who gave permission to publish their names).

How to set a custom property on a channel?

Use wsadminlib's method setChannelCustomProperty().

Before we start, here is an example of channel custom properties in the admin console: Click Application Servers-> server1-> Web container settings-> Web container transport chains-> WCInboundDefault-> Web container inbound channel (WCC2)-> Custom properties. I have no idea what a channel is, but I can show you how to set a custom property on one...

Method setChannelCustomProperty() allows us to specify the channel either by an end point name or the channel name. Take a look at the method in wsadminlib, where there is actually good pydoc to explain the parameters.

The first five parameters are required, in the specified sequence. The last two, endPointName and channelName, are optional and have defaults. You must specify exactly one of them.

So let's add a hypothetical custom property, enablePlayaDust=true, by specifying the channel name. Create a python script file named setChannelCustProp.py: