wsadminlib.py

Fix for bug in method createUsingTemplate()

2012-01-07T08:53:00.000-08:00

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

2011-06-27T10:43:00.000-07:00

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...

After some experimenting and research, we learned that WAS continues to expand the EAR file into specific directories after the sync is complete. And we also learned a way to query when it is done.

AdminApp.isAppReady() will report whether an EAR is fully expanded and ready to start.

The following helper method encapsulates the call to AdminApp. This method returns a boolean value (0 or 1) which is easy for your code to test, whereas the underlying method returns a string 'true'. This method may be added to your copy of wsadminlib.py or used in your own scripts.

def isApplicationReady(appname):
"""Returns True when app deployment is complete and ready to start.
Returns False when the app is not ready or is not recognized.
This method indicates when background processing is complete
following an install, save, and sync.
This method is useful when installing really large EARs."""
m = "isApplicationReady:"
rc = False
try:
if 'true' == AdminApp.isAppReady(appname):
sop(m,"App %s is READY. Returning True." % (appname))
rc = True
else:
sop(m,"App %s is NOT ready. Returning False." % (appname))
except:
sop(m,"App %s is UNKNOWN. Returning False." % (appname))
return rc

If you find this useful, we will include it in the next version of wsadminlib.py. We can also include a method which waits until the app is ready (up to a timeout value). Please let us know.

WAS V8 and wsadminlib.py

2011-06-26T20:07:00.000-07:00

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?

2011-04-18T09:32:00.000-07:00

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>

Next I issued the createReplicationDomain() command and saved it:

wsadmin>domainName = "andyDomain"
wsadmin>numReplicas = -1
wsadmin>
wsadmin>createReplicationDomain( domainName, numReplicas )
wsadmin>
wsadmin>save()

Browsing to the admin console confirms the domain was created: Environment-> Replication Domains

Clicking one step further shows the number of replicas is set to 'Entire Domain', which corresponds to -1 in the wsadminlib.py command.

Then I issued the setServerSessionReplication() command to enable replication on the application server using the just-created domain, and saved it too.

wsadmin>nodeName = "ndnode1"
wsadmin>serverName = "server1"
wsadmin>domainName = "andyDomain"
wsadmin>dataReplicationMode = "BOTH"
wsadmin>
wsadmin>setServerSessionReplication( nodeName, serverName, domainName, dataReplicationMode )
wsadmin>
wsadmin>save()

Finally, browsing to the admin console once again confirms that the server has memory-to-memory replication enabled: Servers-> server1-> Session Management-> Distributed Environment Settings

And clicking one step further shows the selected domain name (ie, andyDomain) and replication mode (ie, both client and server):

Wsadminlib.py also contains methods which create clusters with replication enabled. I have used those methods in years past. This question was interesting to me because I can't remember ever enabling replication for existing servers.

For more information about configuring replication, please browse wsadminlib.py itself. Search for the word 'replication' to discover several special-purpose and general-purpose methods. Read the prologues of each method. They usually give a good description of the acceptable parameters.

Presentation on wsadminlib.py

2011-02-01T05:43:00.000-08:00

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

2011-01-23T10:41:00.000-08:00

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.

2011-01-21T07:03:00.000-08:00

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...

def compareIntLists(a, b):
   """Compares two python lists containing ints.
   Handles arrays of different lengths by padding with zeroes.
   Returns -1 if array a is less than array b. For example,
   [6,0,0,13] < [6,1]
   Returns 0 if they're the same. For example,
   [7,0] = [7,0,0,0]
   Returns +1 if array a is greater than array b. For example,
   [8,0,0,12] > [8,0,0,11]
   """
   m = "compareIntLists:"
   sop(m,"Entry. a=%s b=%s" % ( a, b, ))

   # Make both arrays the same length. Pad the smaller array with trailing zeroes.
   while (len(a) < len(b)):
   a.append(0)
   while (len(b) < len(a)):
   b.append(0)

# Compare each element in the arrays.
rc = cmp(a,b)

   sop(m,"Exit. Returning %i" % ( rc ))
   return rc

The second problem is a small logging bug in method createProtocolProvider(). The initial logging message has single-quotes and double-quotes mismatched. Here is the original buggy line:

   sop (m, "Create Mail Protocol Provider '+protocol+', if it does not exist")

and here is the fix:

   sop (m, "Create Mail Protocol Provider "+protocol+", if it does not exist")

The python language allows use of single and double quotes for strings, but they must be in matched pairs.

Many thanks to wsadminlib user Bryan for reporting these problems.

Updated wsadminlib.py now available

2011-01-14T05:36:00.001-08:00

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 $"

List of changes to wsadminlib.py, January 2011 (in no particular order):

   new:
   setDiskOffloadLocation
   getDeploymentAutostart
   getAdminAppViewValue
   getApplicationContextRoot
   setApplicationContextRoot
   getApplicationVirtualHost
   getNodeNameList
   getServerJvmByRegion
   createJvmPropertyByRegion
   deleteVirtualHost
   configureJPAService
   setWebContainerDefaultVirtualHostName
   enableJava2Security
   disableJava2Security
   updateWASPolicy
   removeSIBusMember
   modifySIBusMemberPolicy
   getJAAS
   isHPELEnabled
   configureHPEL
   configureHPELBinaryLog
   configureHPELTextLog
   configureHPELTrace
   getServerNamedEndPoint
   setCookieConfig
   changeHostName
   listListenerPortsOnServer
   startAllListenerPortsInCluster
   stopAllListenerPortsInCluster
   setInitialStateOfAllListenerPortsInCluster
   smartQuote
   listAllBusinessProcessTemplates
   listAllBusinessProcessTemplatesForApplication
   stopAllBusinessProcessTemplatesForApplicationOnCluster
   stopAllBusinessProcessTemplatesForApplication
   updated:
   stopServer - new parm to specify 'terminate'
   setDeploymentAutostart - fix
   enableLTPALDAPSecurity - new parm enableJava2Security
   enableKerberosSecurity - fix
   addSIBusMember_ext - fix
   createJAAS - return object
   createDerbyDataSource - new parm datasourceName, return object
   deleted:
   getFritzComponent

A review of wsadminlib.py

2011-01-14T04:41:00.000-08:00

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

2011-01-10T20:05:00.000-08:00

- 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?

2010-12-09T13:28:00.000-08:00

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?

Execute operating system commmand 'startNode.sh' or 'startNode.bat'. This command is under /profiles//bin.

For example:
/opt/WAS61/profiles/node1/bin/startNode.sh

4) Hold it there!!! Question 3 describes how to start a Node agent manually and not programmatically. How can I achieve that?

You could use python libraries such as OS or Subprocess to do it. These libraries allow you to execute "external" commands within a script.

For example, the following command will list the contents of the current working directory:

os.system('ls')

5) How can I use these libraries to start a Node agent?

Execute:

os.system(PATH_TO_STARTNODE_SCRIPT)

where PATH_TO_STARTNODE_SCRIPT is the location of your startNode.sh script.

In my case, is something like:

os.system('/opt/WAS61/profiles/node1/bin/startNode.sh')

Below is a script that exercises these concepts. It checks the status of a Node agent. If it is running, the script issues a command to stop it; else it issues a command to start it.

Script:

# Import python os library to execute external commands
import os

# Import wsadminlib.py (update this to your own wsadminlib.py path)
execfile('/tmp/wsadminlib.py')

# Node name
nodename = 'node1'

# Server name
servername = 'nodeagent'

# Counter used to keep track of while loop execution
counter = 0

while(counter < 2):
   # Check if Node agent is running
   print "\nIs Node agent running?"
   isItRunning = isServerRunning(nodename,servername)

   # If Node agent is running let's stop it
   # else let's start it
   if (isItRunning):
   print "YES\n"

   print "Request issued to stop Node agent\n"
   stopServer( nodename, servername, immediate=False )
   counter = counter + 1
   else:
   print "NO\n"
   print "Request issued to start Node agent\n"
   os.system('/opt/WAS61/profiles/node1/bin/startNode.sh')
   counter = counter + 1

Script Output:

Is Node agent running?
YES

Request issued to stop Node agent

WASX7337I: Invoked stop for server "nodeagent" Waiting for stop completion.

Is Node agent running?
NO

Request issued to start Node agent

ADMU0116I: Tool information is being logged in file
   /opt/WAS61/profiles/node1/logs/nodeagent/startServer.log
ADMU0128I: Starting tool with the node1 profile
ADMU3100I: Reading configuration for server: nodeagent
ADMU3200I: Server launched. Waiting for initialization status.
ADMU3000I: Server nodeagent open for e-business; process id is 24175

Request for Feedback

2010-12-01T07:49:00.000-08:00

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

2010-11-11T09:51:00.000-08:00

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...

Now set the return value to the same name as the method. The return variable has the expected value, but the variable has unknowingly converted the name from a callable method to an integer.

>>> myMethod = myMethod(3,4)
>>> print myMethod
7
>>>

When we repeat the previously-successful call, it fails. The error message says the variable type, an int, is 'not callable' as a method.

>>> k = myMethod(1,2)
Traceback (most recent call last):
File "", line 1, in
TypeError: 'int' object is not callable
>>>

A wsadminlib user recently reported a problem where this behavior was the culprit. The calling script inadvertently defined a variable with the same name as a method in wsadminlib.py. For example, the script had something like this:

isND = isND()

Everything worked fine until much later, when subsequent code tried to query isND() once again. Poof, the 'not callable' error appeared.

Lesson: if ever you see a 'not callable' error, search and examine every location where the method name is used.

How to set custom properties in Global Security?

2010-08-16T07:14:00.000-07:00

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?

2010-07-09T13:30:00.000-07:00

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?

The second time I encountered this format, I wrote a helper method in wsadminlib.py to abstract it.

Method propsToDictionary() accepts this type of string as input, and returns a python dictionary as output, where each key and value are elements of the dictionary.

To demonstrate, we first start wsadmin and load wsadminlib.py:

root@ding6:/tmp# /opt/WAS70/bin/wsadmin.sh -lang jython -host ding4 -port 8879
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
WASX7031I: For help, enter: "print Help.help()"
wsadmin>
wsadmin>execfile('/tmp/wsadminlib.py')
$Id: wsadminlib.py 104 2010-02-15 19:06:18Z ding $
wsadmin>
wsadmin>enableDebugMessages()
[2010-0709-1540-2100] enableDebugMessages Verbose trace messages are now enabled; future debug messages will now be printed.
wsadmin>

Now let's define an input string in the format of responses from several wsadmin commands, and convert to a python dictionary:

wsadmin>propString = '[ [key0 value0] [key1 value1] [key2 value2] ]'
wsadmin>
wsadmin>propDict = propsToDictionary(propString)
wsadmin>
wsadmin>print propDict
{'key2': 'value2', 'key1': 'value1', 'key0': 'value0'}
wsadmin>

It is really easy to call this method from your code and then extract desired values. Here we get the value for key1:

wsadmin>myValue1 = propDict['key1']
wsadmin>
wsadmin>print myValue1
value1
wsadmin>

Example 2

Another example is helper method stringListToList(). It takes a string which looks like a list as input:

'[element0 element1 element2]'

and returns a python list object containing each element as a string:

['element0', 'element1', 'element2']

It is much easier and natural to deal with a list of information in python list object, rather than in a string.

Availablilty

These and other helper methods are used internally within wsadminlib.py. You are able to make use of them from your own external methods as well.

Please look for these and similar helper methods in wsadminlib.py the next time you encounter an ugly 'object-like' string from wsadmin. The input/output syntax of each helper method is well-documented at the top of each method.

Friday Quiz

As a community-contribution project, wsadminlib.py is not perfect. As I was typing this blog entry, I discovered a second method in wsadminlib which seems to implements the same functionality as propsToDictionary(). Maybe I will deprecate one someday. Meanwhile, see if you can find it while you are savoring all the valuables in wsadminlib.py!

How to install an application?

2010-05-12T08:44:00.000-07:00

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.

filename = '/tmp/pxyapps.ear'
servers = [ { 'nodename': 'node1', 'servername': 'sippbx1' } ]
installApplication( filename, servers, [], None )

After saving the config, we again browse to the admin console, and see the app's mappings"

But wait, there's more. If you browse through wsadminlib.py, in the section titled 'application-related methods', you'll find a bevy of methods to list applications, delete them, start and stop, etc. Poke around and see what you can find.

Just for the archives, here is the full transcript of installing on the cluster...

root@ding1:/tmp# /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
WASX7031I: For help, enter: "print Help.help()"
wsadmin>
wsadmin>
wsadmin>execfile('/tmp/wsadminlib.py')
$Id: wsadminlib.py 104 2010-02-15 19:06:18Z ding $
wsadmin>
wsadmin>
wsadmin>enableDebugMessages()
[2010-0512-1007-1600] enableDebugMessages Verbose trace messages are now enabled; future debug messages will now be printed.
wsadmin>
wsadmin>
wsadmin>filename = '/tmp/pxyapps.ear'
wsadmin>clusternames = [ 'cluster1' ]
wsadmin>
wsadmin>
wsadmin>installApplication( filename, [], clusternames, None )
[2010-0512-1020-4200] installApplication: filename=/tmp/pxyapps.ear, servers=[], clusternames=['cluster1'], options=None
[2010-0512-1020-4200] installApplication: Calling AdminApp.install of /tmp/pxyapps.ear with arglist = ['-target', 'WebSphere:cell=ndcell,cluster=cluster1']
ADMA0073W: Custom permissions are found in the [(com.ibm.websphere.security.WebSphereRuntimePermission AdminPermission)] policy file. Custom permissions can compromise the integrity of Java 2 Security.
WASX7327I: Contents of was.policy file:
/*
* WARNING: IF YOU EDIT THIS FILE WITH THE policytool, THESE
* COMMENTS MIGHT BE LOST
*/

grant codeBase "file:${application}" {

/* Pxyapps needs this - it tries to get the cell name */
permission com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission";

permission java.io.FilePermission "${was.install.root}${/}properties${/}version${/}CEA.product", "read";
permission java.lang.RuntimePermission "accessClassInPackage.sun.misc";

permission java.security.AllPermission;
};

ADMA5016I: Installation of pxyapps started.
ADMA5058I: Application and module versions are validated with versions of deployment targets.
ADMA5005I: The application pxyapps is configured in the WebSphere Application Server repository.
ADMA5053I: The library references for the installed optional package are created.
ADMA5005I: The application pxyapps is configured in the WebSphere Application Server repository.
ADMA5001I: The application binaries are saved in /opt/WAS70/profiles/dmgr/wstemp/Script1288cd6bd3d/workspace/cells/ndcell/applications/pxyapps.ear/pxyapps.ear
ADMA5005I: The application pxyapps is configured in the WebSphere Application Server repository.
SECJ0400I: Successfully updated the application pxyapps with the appContextIDForSecurity information.
ADMA5005I: The application pxyapps is configured in the WebSphere Application Server repository.
ADMA5113I: Activation plan created successfully.
ADMA5011I: The cleanup of the temp directory for application pxyapps is complete.
ADMA5013I: Application pxyapps installed successfully.
wsadmin>
wsadmin>
wsadmin>save()
[2010-0512-1020-4700] save: AdminConfig.queryChanges()
[2010-0512-1020-4700] save: WASX7146I: The following configuration files contain unsaved changes:
[2010-0512-1020-4700] save: cells/ndcell/nodes/node1/serverindex.xml
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deltas/pxyapps/delta-1273674004465
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/pxyapps.ear
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/META-INF/ibm-application-bnd.xmi
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/META-INF/MANIFEST.MF
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/pxyapps.war/WEB-INF/ibm-web-bnd.xmi
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/META-INF/application.xml
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/pxyapps.war/WEB-INF/web.xml
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/pxyapps.war/META-INF/MANIFEST.MF
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/pxyapps.war/WEB-INF/ibm-web-ext.xmi
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/META-INF/was.policy
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/META-INF/ibm-application-runtime.props
[2010-0512-1020-4700] save: cells/ndcell/applications/pxyapps.ear/deployments/pxyapps/deployment.xml
[2010-0512-1020-4700] save: cells/ndcell/blas/pxyapps/bver/BASE/bla.xml
[2010-0512-1020-4700] save: cells/ndcell/cus/pxyapps/cver/BASE/cu-ref.xml
[2010-0512-1020-4700] save: cells/ndcell/cus/pxyapps/cver/BASE/controlOpDefs.xml
[2010-0512-1020-4700] save: cells/ndcell/cus/pxyapps/cver/BASE/cu.xml
[2010-0512-1020-4700] save: AdminConfig.getSaveMode()
[2010-0512-1020-4700] save: rollbackOnConflict
[2010-0512-1020-4700] save: AdminConfig.save()
[2010-0512-1020-4800] save: Save complete!
[2010-0512-1020-4800] wsadminlib.syncall Start
[2010-0512-1020-4900] wsadminlib.syncall Sync config to node node1
[2010-0512-1020-4900] wsadminlib.syncall Done
0
wsadmin>
wsadmin>

How to create a cluster and servers?

2010-04-21T05:49:00.000-07:00

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:

createCluster( 'cell1', 'cluster1', createReplicationDomain=True )
createServerInCluster( 'cluster1', 'node1', 'server1', sessionReplication=True )
createServerInCluster( 'cluster1', 'node1', 'server2', sessionReplication=True )

Note: True and False are set to 1 and 0 in wsadminlib.py as a convenience.

This creates a replication domain with the same name as the cluster.

Finally, I created a python file to do all of the above. I named it clusterdemo.py. I invoked it like this:

/opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879 -f clusterdemo.py

And here are the contents. Feel free to copy, paste, and tweak.

#-----------------------------------------------------------------------
# This python script demonstrates how
# to create a cluster with two servers
# using wsadminlib.py
#
# AD 2010-0421-0800
#-----------------------------------------------------------------------
execfile('wsadminlib.py')
enableDebugMessages()
m = "clusterdemo.py:"
sop(m,"Entry.")

# Define variable names
clustername = "cluster1"
server1name = "server1"
server2name = "server2"

# Debug
sop(m,"clustername=" + clustername)
sop(m,"server1name=" + server1name)
sop(m,"server2name=" + server2name)

# Specify replication
createReplicationDomain = True
sessionReplication = True

# Query the cell name.
cellname = getCellName()
sop(m,"cellname=" + cellname)

# Query the first node name.
nodelist = listAppServerNodes()
nodename = nodelist[0]
sop(m,"nodename=" + nodename)

# Create the cluster.
createCluster( cellname, clustername, createReplicationDomain )

# Create each server within the cluster.
createServerInCluster( clustername, nodename, server1name, sessionReplication )
createServerInCluster( clustername, nodename, server2name, sessionReplication )

# Save and synchronize
save()

sop(m,"Exit.")

Who wrote wsadminlib.py?

2010-04-09T07:56:00.001-07:00

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?

2010-04-02T06:25:00.000-07:00

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:

execfile('wsadminlib.py')
enableDebugMessages()

# Define the parameters.
nodename = 'node1'
servername = 'server1'
propname = 'enablePlayaDust'
propvalue = 'true'
channeltype = 'WebContainerInboundChannel'
channelname = 'WCC_2'

# Set the property
setChannelCustomProperty(nodename, servername, propname, propvalue, channeltype, channelName = channelname)

# Save and sync to all nodes.
save()

Then run it...

root@ding6:/# /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879 -f setChannelCustProp.py
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
$Id: wsadminlib.py 50 2009-01-14 14:42:11Z ding $
[2010-0402-1000-0100] enableDebugMessages Verbose trace messages are now enabled; future debug messages will now be printed.
[2010-0402-1000-0100] setChannelCustomProperty: Entry. Setting channel custom property enablePlayaDust=true on node1/server1 channelType=WebContainerInboundChannel endPointName=None channelName=WCC_2
[2010-0402-1000-0200] save: AdminConfig.queryChanges()
[2010-0402-1000-0200] save: WASX7146I: The following configuration files contain unsaved changes:
[2010-0402-1000-0200] save: cells/ndcell/nodes/node1/servers/server1/server.xml
[2010-0402-1000-0200] save: AdminConfig.hasChanges()
[2010-0402-1000-0200] save: AdminConfig.getSaveMode()
[2010-0402-1000-0200] save: rollbackOnConflict
[2010-0402-1000-0200] save: AdminConfig.save()
[2010-0402-1000-0200] save: Save complete!
[2010-0402-1000-0200] wsadminlib.syncall Start
[2010-0402-1000-0300] wsadminlib.syncall Sync config to node node1
[2010-0402-1000-0300] wsadminlib.syncall Done

There were no errors and no exceptions, so that means the channel was found and the prop was set successfully.

To confirm the results, refresh the view on the admin console, and we can see the property named 'enablePlayaDust' with the value 'true'. Et voila.

PS: Here's a snippet to set a custom prop using the endPointName:

channeltype = 'UDPInboundChannel'
endpointname = 'SIP_DEFAULTHOST'
setChannelCustomProperty(nodename, servername, propname, propvalue, channeltype, endPointName = endpointname)

How to set a server's listening port number?

2010-03-31T09:12:00.000-07:00

Use wsadminlib's method setServerPort(). Here's an example of setting the web container's default port:

nodename = 'node1'
servername = 'server1'
endPointName = 'WC_defaulthost'
port = 9083
setServerPort(nodename, servername, endPointName, port)

Note that the name arguments are python strings, but the port is a number. Here is a screenshot:

root@ding6 /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
WASX7031I: For help, enter: "print Help.help()"
wsadmin>
wsadmin>execfile('wsadminlib.py')
$Id: wsadminlib.py 50 2009-01-14 14:42:11Z ding $
wsadmin>
wsadmin>enableDebugMessages()
[2010-0301-1232-1200] enableDebugMessages Verbose trace messages are now enabled; future debug messages will now be printed.
wsadmin>
wsadmin>
wsadmin>nodename = 'node1'
wsadmin>servername = 'server1'
wsadmin>endPointName = 'WC_defaulthost'
wsadmin>port = 9083
wsadmin>
wsadmin>setServerPort(nodename, servername, endPointName, port)
wsadmin>

Option: If you look at the method signature, you'll see that a hostname parameter (or IP) can be specified for this port definition. It defaults to the asterisk wildcard. For example,

wsadmin>hostname = 'ding6.raleigh.ibm.com'
wsadmin>setServerPort(nodename, servername, endPointName, port, hostname)
wsadmin>

Also note this method is not very chatty, since it prints no messages on success. You'll find differences in verbosity throughout wsadminlib, depending upon who wrote the method. Fear not, most setters have getters, and you can query the value after setting it:

wsadmin>getServerPort(nodename, servername, endPointName)
'9083'
wsadmin>

How to save my changes?

2010-03-30T08:58:00.000-07:00

Use wsadminlib's method save(). This method saves your changes and pushes them out to all the nodes immediately (if you are running in a cell environment). It also displays all the changes, for debug purposes.

Here is a screenshot from the end of an exercise where I created a new server:

wsadmin>save()
[2010-0301-1150-2400] save: AdminConfig.queryChanges()
[2010-0301-1150-2400] save: WASX7146I: The following configuration files contain unsaved changes:
[2010-0301-1150-2400] save: cells/ndcell/nodes/node1/servers/server1/server.xml
[2010-0301-1150-2400] save: AdminConfig.hasChanges()
[2010-0301-1150-2400] save: AdminConfig.getSaveMode()
[2010-0301-1150-2400] save: rollbackOnConflict
[2010-0301-1150-2400] save: AdminConfig.save()
[2010-0301-1150-2400] save: Save complete!
[2010-0301-1150-2500] wsadminlib.syncall Start
[2010-0301-1150-2500] wsadminlib.syncall Sync config to node node1
[2010-0301-1150-2600] wsadminlib.syncall Done
0
wsadmin>

How to set the trace spec on a server?

2010-03-29T08:41:00.000-07:00

Use wsadminlib's method setServerTrace(). Here is a simple example:

nodename = 'node1'
servername = 'server1'
tracespec = '*=info:com.ibm.ws.sip.*=all'
setServerTrace(nodename, servername, tracespec)

And a screen capture:

root@ding6: /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
WASX7031I: For help, enter: "print Help.help()"
wsadmin>
wsadmin>execfile('wsadminlib.py')
$Id: wsadminlib.py 50 2009-01-14 14:42:11Z ding $
wsadmin>
wsadmin>enableDebugMessages()
[2010-0301-1149-3100] enableDebugMessages Verbose trace messages are now enabled; future debug messages will now be printed.
wsadmin>
wsadmin>nodename = 'node1'
wsadmin>servername = 'server1'
wsadmin>tracespec = '*=info:com.ibm.ws.sip.*=all'
wsadmin>setServerTrace(nodename, servername, tracespec)
[2010-0301-1150-0800] setServerTrace: Setting tracing on server node1/server1 to *=info:com.ibm.ws.sip.*=all
wsadmin>

Be sure to take a look at the method in wsadminlib.py. It has defaults which you can override for the number and size of backup log files. And on z/OS, it automatically stores the log files in the same location as they appear on non-Z platforms.

What is this method sop()?

2010-03-28T11:02:00.000-07:00

wsadminlib.py has a rudimentary trace/logging facility in method sop(). The name is a snarky acronym taken from Java's System.out.println() command.

Input: Method sop() takes two strings as parameters, the name of the calling method, and the message.

Output: Method sop() prints these to the console, along with a terse, internationally-understandable timestamp: [YYYY-MMDD-hhmm-ss00]

You can turn these messages on and off dynamically by calling these toggle methods:
- enableDebugMessages()
- disableDebugMessages()
sop() messages are disabled by default. I like verbose messages, so all of my scripts call enableDebugMessages() right at the start.

Note that wsadminlib contains many calls to sop() which are commented-out. These are usually very verbose messages which were written by the original method developer, but not needed since. However, we left them in intentionally. If you are having trouble making a specific method work, or you want to see the gory details for use in your own method, try uncommenting some of these messages for extra hints.

Oh, and one more thing. You can call method sop() from your own script files as well. That way, your messages will have the same fancy timestamp as wsadminlib's, and your messages will look consistent with wsadminlib's too (which I find makes everything easier to read).

How to use wsadminlib.py

2010-03-27T09:17:00.000-07:00

There are several ways to make use of wsadminlib. Here are the basic ideas...

1. Reference

If you are looking for the secrets of how to issue some command, browse wsadminlib and search for it. We try to keep related methods together, so you should find similar functions nearby. If you don't find what you need, search the entire file, case-insensitive.

2. Sample code

If you find something you like, feel free to copy/paste from wsadminlib to your own scripts. wsadminlib is provided as a free sample. And if you find something you don't like, feel free to copy and change it.

3. Call from wsadmin shell

You can call methods in wsadminlib directly from the wsadmin shell. I find this really handy when I am setting up a one-time test. For example, go to a command-prompt, and open a wsadmin connection to your deployment manager.

root@ding6:~# /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
WASX7031I: For help, enter: "print Help.help()"
wsadmin>

Include wsadminlib.py:

wsadmin>execfile('/tmp/wsadminlib.py')
$Id: wsadminlib.py 104 2010-02-15 19:06:18Z ding $
wsadmin>

Call a method. For example, list all the servers which exist. This is handy for debug when running things manually:

wsadmin>serverStatus()
Server status
=============
NODE dmgr on ding6 (linux) - Deployment manager
NODE node1 on ding6 (linux)
APPLICATION_SERVER fritzserver stopped
NODE_AGENT nodeagent running
APPLICATION_SERVER server1 stopped
APPLICATION_SERVER sippbx1 stopped
APPLICATIONS:
commsvc.pbx
commsvc.testear
fritzlet_ear
wsadmin>

4. Call from your own scripts

I write my own small script files when I need to set up a complex configuration repeatedly, and don't want to keep typing the same commands over and over. These scripts are small, because they call methods in wsadminlib.py to do all the work. Here is a a simple example of a script which starts a server. Create a python file like this:

root@ding6:/tmp# cat wsadminlib.demo.py
execfile('/tmp/wsadminlib.py')
enableDebugMessages()

# Start server1
servername = 'server1'
nodename = 'node1'
startServer(nodename,servername)

Invoke it and watch the progress:

root@ding6:/tmp# /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879 -f /tmp/wsadminlib.demo.py
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
$Id: wsadminlib.py 104 2010-02-15 19:06:18Z ding $
[2010-0329-1341-2800] enableDebugMessages Verbose trace messages are now enabled; future debug messages will now be printed.
[2010-0329-1341-2800] startServer: starting server node1,server1
[2010-0329-1341-2800] startServer: startServer(server1,node1)
[2010-0329-1341-4300] startServer: server node1,server1 not running yet, waiting another 15 secs

Looking at the wsadminlib source code, we see the startServer() method exits silently upon success, and raises a python exception if anything goes wrong. Therefore, the server started successfully. We also see that the method checks every so often to see if the server has started. This provides reassurance that the script is still alive and just waiting for results, especially when you have a mix of fast and slow server machines.

Welcome to wsadminlib.py

2010-03-26T08:06:00.000-07:00

Overview

wsadminlib.py is a large python file containing hundreds of methods to help simplify configuring the IBM WebSphere Application Server (WAS) product using scripting.

Where do I get it?

Click here [developerWorks] and search for 'wsadminlib'. Its official name is "The IBM WebSphere Application Server Sample Script (wsadminlib.py package)".

Design goals

wsadminlib.py was designed to simplify configuration of the IBM WebSphere Application Server (WAS) product by providing much-improved understandability and ease-of-use. The underlying scripting syntax for configuring the WAS product can be complex and challenging to understand. The wsadminlib package was created to provide simple method names and simple parameter names, and hide the underlying nonsense.

A wide variety of methods have been developed. These methods perform tasks such as creating servers, starting servers, creating clusters, installing applications, proxies, core groups, core group bridge, dynacache, shared libraries, classloaders, replication domains, security, BLA, JDBC, etc, etc, etc.

History

wsadminlib.py was originally created in 2006 by two IBM product developers who were having trouble understanding the native wsadmin syntax. They were both encountering the same problems and both spending time researching the same solutions. They joined forces to split the work and share the benefits, and the original wsadminlib.py was born.

By word of mouth, other teammates discovered the joys of wsadminlib, using it as both a code reference and in production. Eventually, many of these teammates began contributing new methods which they had researched and debugged, thus sharing solutions with others.

Community interest grew steadily over time. By 2010, several dozen people had contributed methods related to component areas they understood, and wsadminlib was being used in production by a good number of components in the current strategic agile automated test infrastructure.

Other script packages

wsadminlib is one of many sample script packages available from IBM and others. Here are some comparisons to guide your selection. Pick your favorite. Vive la difference.

- The developers of wsadminlib like having everything in one monolithic file. There is only one file to include, and only one place to search. Other script developers prefer smaller files, organized in subdirectories, in a more object-oriented fashion.

- The developers of wsadminlib strive to write methods with self-documenting names, and intuitively named parameters. They write pydoc only when necessary. Other script developers like to write verbose documentation.

- Other packages may support multiple languages. Wsadminlib is English-only.

Limitations

- Error-handling is not consistent. Some methods raise python exceptions, others use a return code.

- All wsadminlib methods work well on WAS V7 and V8 (beta). Some methods work on V6.1, but not all have been tested. WAS 6.0.2 is unknown.

- wsadminlib is not a formally-supported product. It is provided as a sample, on an as-is basis. The official disclaimer is in the prologue at the top of wsadminlib.py.

Summary

wsadminlib has been very helpful to many of us inside IBM to speed development of configuration scripts and to run testcases. We hope you find something useful too.