Updating wps.ear using WSAdmin Script

The WebSphere Portal engine is implemented as J2EE application. The portal engine logic is implemented in wps.ear. These are some of the use cases in which you might want to update the wps.ear

• You want to introduce a new THeme or Skin or something that is deployed as part of wps.ear


• You might want to add Servlet Filter to do some pre/post processing on the portal engine requests.

I am working on creating a new Theme and Skin and as part of that i need to update the wps.ear frequently and i follow these steps to update wps.ear using wsadmin script

• First connect to wsadmin console for WebSphere Portal, you can do that by executing following command
  
./wsadmin.sh -user wasadmin -password wasadmin -lang jython -port 10033

  By default the portal is configured to listen on 10033 port for SOAP connection
  


• THen execute AdminApp.export('appname','eardestinationpath') command on the wsadmin consoel and it will export the installed application into .ear
  
AdminApp.export('wps','/tmp/wpsear/wps.ear')

  In this case i am export wps enterprise application into /tmp/wpsear/wps.ear
  


• The wps.ear contains 3 .war files and one .ejb.jar file. I can use either normal jar utility to expand the .ear first and then expand .war files in the .ear file or i can use EARExpander utility which is part of WAS and available even in profile_home/bin directory to expand the .ear file
  
./EARExpander.sh -ear /tmp/wpsear/wps.ear -operationDir /tmp/wpsear -operation expand -expansionFlags all

  This will expand the wps.ear and the .war files inside into /tmp/wpsear directory
  


• Now you can apply your changes by either copying new theme or skin related directory or modifying the web.xml file for adding filter definition
  


• We can use the EARExpander utility to collapsing the content of directory into .ear file using command like this
  
./EARExpander.sh -ear /tmp/wps.ear -operationDir /tmp/wpsear -operation collapse

  


• Once the updated wps.ear is ready we can use the following wasadmin command to update the .ear file on the server
  
AdminApp.update('wps', 'app', '[ -operation update -contents /tmp/wps.ear -nopreCompileJSPs -installed.ear.destination $(APP_INSTALL_ROOT)/DefaultNode -distributeApp -nouseMetaDataFromBinary -nodeployejb -createMBeansForResources -noreloadEnabled -nodeployws -validateinstall warn -processEmbeddedConfig -filepermission .*\.dll=755#.*\.so=755#.*\.a=755#.*\.sl=755 -noallowDispatchRemoteInclude -noallowServiceRemoteInclude]' )

  


• Last step would be to commit changes in the WAS configuration, at this point the WAS xml configuration files will actually get modified
  
AdminConfig.save()

  

wsadmin script for creating cluster and adding cluster members

You can use this Jython script to create cluster and add members to it

AdminTask.createCluster('[-clusterConfig [-clusterName samplecluster] -replicationDomain [-createDomain true]]')

AdminTask.createClusterMember('[-clusterName samplecluster -memberConfig [-memberNode dmgrNode01 -memberName SampleMember1 -memberWeight 2 -replicatorEntry true] -firstMember [-templateName "Sample Template" -nodeGroup DefaultNodeGroup -coreGroup DefaultCoreGroup]]')

AdminTask.createClusterMember('[-clusterName samplecluster -memberConfig [-memberNode sunpatilNode02 -memberName SampleMember2 -memberWeight 2 -replicatorEntry true]]')


This script creates samplecluster by calling AdminTask.createCluster command and then creates SampleMember1 as cluster member using AdminTask.createClusterMember call. The AdminTask.createClusterMember is made for adding additional cluster members

WSAdmin Objects

The wsadmin command exposes following four objects

1. AdminControl:The AdminControl scripting object is used for operational control. It communicates with MBeans that represent live objects running a WebSphere server process. It includes commands to query existing running objects and their attributes and invoke operations on the objects.


2. AdminConfig: The AdminConfig object is used to manage the configuration information that is stored in the repository. This object communicates with the WebSphere Application Server configuration service component to make configuration inquires and changes. In a distributed server environment, the AdminConfig commands are available only if a scripting client is connected to the deployment manager. When connected to a node agent or a managed application server, the AdminConfig commands will not be available because the configuration for these server processes are copies of the master configuration that resides in the deployment manager.


3. AdminApp: The AdminApp object can update application metadata, map virtual hosts to Web modules, and map servers to modules for applications already installed. Changes to an application, such as specifying a library for the application to use or setting session management configuration properties, are performed using the AdminConfig object.


4. AdminTask: The AdminTask object is used to access a set of task-oriented administrative commands that provide an alternative way to access the configuration commands and the running object management commands. The administrative commands run simple and complex commands. The administrative commands are discovered dynamically when the scripting client is started. The set of available administrative commands depends on the edition of WebSphere Application Server you install. You can use the AdminTask object commands to access these commands.

WSAdmin command invocation

The wsadmin command can be invoked in three different ways

• Invoking Single command: You can invoke single command of wsadmin by executing wsadmin -c AdminControl.getNode()


• Invoking commands interactively: If you want to execute more than one command then you can execute wsadmin in interactive mode, This is the default mode of wsadmin and you can invoke it by not passing either -c or -f options. Once you do that the wsadmin prompt will appear and you can execute wsadmin scripting commands on the prompt.


• Running script file (-f): If you have set of predefined scripts then you can execute wsadmin -f <filename> command to execute the script file.

Rational application developer has a Jython development perspective that lets you develop and execute Jython commands from within IDE and it also lets you debug your script

In this screen shot i am executing createWASVariable.py script from IDE on my DMGR. I need to specify soap port of DMGR and Admin user login information here

WSAdmin security hardening

When you execute the wsadmin script you will have to pass the username and password for the user as command line parameter. But one of my client had this hardening requirement that we should not pass user name and password on command line because if someone is running ps at the same time they could see the command line parameters. Since i was writing automation script i could not prompt user for user name password. So i did set following things

• Change \profiles\AppSrv01\properties\soap.client.properties file,
  set value of com.ibm.SOAP.loginUserid property to the userId of the admin user and value of com.ibm.SOAP.loginPassword property to the password of the admin user and then set value of com.ibm.SOAP.loginSource property to blank.
  
com.ibm.SOAP.loginUserid=wasadmin
com.ibm.SOAP.loginPassword=wasadmin

#------------------------------------------------------------------------------
# SOAP Login Prompt
#
# The auto prompting will happen only if all of the following are met:
#
# - Running from a SOAP client
# - Server is reachable and server security is enabled
# - Username and password are not provided either on command line or in this
# file
# - com.ibm.SOAP.loginSource below is set to either "stdin" or "prompt"
#
# stdin: prompt in command window
# prompt: GUI dialog box; falls back to stdin if GUI not allowed
#
# (So to disable auto prompting, set loginSource to nothing)
#------------------------------------------------------------------------------
com.ibm.SOAP.loginSource=

  


• Now the password is set in plain text which is a security problem so you can use the PropFilePasswordEncoder utility to encode the admin user password in the soap.client.properties file.
  

View administrative script command for last action

WebSPhere Application Server 6.1 has this cool feature, that when you perform some adminstrative action using the WAS Admin console, it will let you get the Wsadmin script command to for the action that you performed using WAS COnsole

I tried installing ConnectionLeak.Ear file and i used the default options for every thing, on the last screen of Install application wizard i saw "View administrative scripting command for last action" link on the right hand side. Clicking on that link generates the equivalent wsadmin command like this



I can save the command as a script file and then execute it from the command line. This feature is very helpful when your trying to automate administration, first you can perform the administrative command using WAS Admin console and then copy script, and parameterize it.

Enable trace for wsadmin script

You can enable trace for tracking transaction and debugging problems when you execute the wsadmin script. You can do that by setting these two properties in the wsadmin.properties file


#-------------------------------------------------------------------------
# The traceFile property determines where trace and logging
# output are directed. If more than one user will be using
# wsadmin simultaneously, different traceFile properties should
# be set in user properties files.
# The default is that all tracing and logging go to the console;
# it is recommended that a value be specified here.
# If the file name contains DBCS characters, use unicode format such as \uxxxx, where xxxx is a number
#-------------------------------------------------------------------------
com.ibm.ws.scripting.traceFile=C:/Cert/WebSphere/AppServer/profiles/Dmgr01/logs/wsadmin.traceout

#-------------------------------------------------------------------------
# The traceString property governs the trace in effect for
# the scripting client process.
# The default is no tracing.
#-------------------------------------------------------------------------
com.ibm.ws.scripting.traceString=com.ibm.*=all=enabled


By default com.ibm.ws.scripting.traceString property is commented so first uncomment it. You can also change the location of the trace file which is logs folder by default.

I tried enabling the trace and then installing enterprise application using wsadmin script, it generates lots of log statements like these


[8/18/09 11:05:59:535 PDT] 0000000a AbstractShell > normalizeFQPathName - C:/Cert/WebSphere/AppServer/bin/securityProcs.jacl;C:/Cert/WebSphere/AppServer/bin/LTPA_LDAPSecurityProcs.jacl Entry
[8/18/09 11:05:59:535 PDT] 0000000a AbstractShell 3 path after converting separator: C:\Cert\WebSphere\AppServer\bin\securityProcs.jacl;C:\Cert\WebSphere\AppServer\bin\LTPA_LDAPSecurityProcs.jacl
[8/18/09 11:05:59:535 PDT] 0000000a AbstractShell < normalizeFQPathName - C:\Cert\WebSphere\AppServer\bin\securityProcs.jacl;C:\Cert\WebSphere\AppServer\bin\LTPA_LDAPSecurityProcs.jacl Exit
[8/18/09 11:05:59:535 PDT] 0000000a WasxShell 3 processing profile: C:\Cert\WebSphere\AppServer\bin\securityProcs.jacl
[8/18/09 11:05:59:535 PDT] 0000000a WasxShell 3 converted profile name: C:\Cert\WebSphere\AppServer\bin\securityProcs.py
[8/18/09 11:05:59:535 PDT] 0000000a WasxShell 3 using language: jython
[8/18/09 11:05:59:550 PDT] 0000000a AbstractShell > getSanitizedScriptString Entry
[8/18/09 11:05:59:550 PDT] 0000000a AbstractShell < getSanitizedScriptString Exit
[8/18/09 11:05:59:566 PDT] 0000000a WasxShell 3 processing profile: C:\Cert\WebSphere\AppServer\bin\LTPA_LDAPSecurityProcs.jacl
[8/18/09 11:05:59:566 PDT] 0000000a WasxShell 3 converted profile name: C:\Cert\WebSphere\AppServer\bin\LTPA_LDAPSecurityProcs.py
[8/18/09 11:05:59:566 PDT] 0000000a WasxShell 3 using language: jython
[8/18/09 11:05:59:597 PDT] 0000000a AbstractShell > getSanitizedScriptString Entry
[8/18/09 11:05:59:597 PDT] 0000000a AbstractShell < getSanitizedScriptString Exit
[8/18/09 11:05:59:644 PDT] 0000000a WasxShell < executeProfiles Exit
[8/18/09 11:05:59:644 PDT] 0000000a AbstractShell > executeCommands Entry
[8/18/09 11:05:59:644 PDT] 0000000a AbstractShell 3 executeScript c:/temp/appinstall.py
[8/18/09 11:05:59:644 PDT] 0000000a AbstractShell > executeScript Entry
[8/18/09 11:05:59:644 PDT] 0000000a AbstractShell 3 using language: jython
[8/18/09 11:05:59:660 PDT] 0000000a AbstractShell A WASX7091I: Executing script: "c:/temp/appinstall.py"
[8/18/09 11:05:59:660 PDT] 0000000a AbstractShell > getSanitizedScriptString Entry
[8/18/09 11:05:59:660 PDT] 0000000a AbstractShell < getSanitizedScriptString Exit
[8/18/09 11:05:59:660 PDT] 0000000a AdminAppClien > install: Entry
c:/temp/ConnectionLeakEAR.ear
[ -nopreCompileJSPs -distributeApp -nouseMetaDataFromBinary -nodeployejb -appname ConnectionLeakEAR -createMBeansForResources -noreloadEnabled -nodeployws -validateinstall warn -noprocessEmbeddedConfig -filepermission .*\.dll=755#.*\.so=755#.*\.a=755#.*\.sl=755 -noallowDispatchRemoteInclude -noallowServiceRemoteInclude]
[8/18/09 11:05:59:660 PDT] 0000000a AbstractShell > setLastException Entry
[8/18/09 11:05:59:660 PDT] 0000000a AbstractShell 3 in script mode; not saving exception
[8/18/09 11:05:59:660 PDT] 0000000a AdminAppClien > doInstall Entry
c:/temp/ConnectionLeakEAR.ear
[ -nopreCompileJSPs -distributeApp -nouseMetaDataFromBinary -nodeployejb -appname ConnectionLeakEAR -createMBeansForResources -noreloadEnabled -nodeployws -validateinstall warn -noprocessEmbeddedConfig -filepermission .*\.dll=755#.*\.so=755#.*\.a=755#.*\.sl=755 -noallowDispatchRemoteInclude -noallowServiceRemoteInclude]
false
[8/18/09 11:05:59:660 PDT] 0000000a LanguageUtili > optionsToHashtable -- [ -nopreCompileJSPs -distributeApp -nouseMetaDataFromBinary -nodeployejb -appname ConnectionLeakEAR -createMBeansForResources -noreloadEnabled -nodeployws -validateinstall warn -noprocessEmbeddedConfig -filepermission .*\.dll=755#.*\.so=755#.*\.a=755#.*\.sl=755 -noallowDispatchRemoteInclude -noallowServiceRemoteInclude] Entry
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti > cleanAttributeString Entry
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti < cleanAttributeString -- -nopreCompileJSPs -distributeApp -nouseMetaDataFromBinary -nodeployejb -appname ConnectionLeakEAR -createMBeansForResources -noreloadEnabled -nodeployws -validateinstall warn -noprocessEmbeddedConfig -filepermission .*\.dll=755#.*\.so=755#.*\.a=755#.*\.sl=755 -noallowDispatchRemoteInclude -noallowServiceRemoteInclude Exit
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti > getTokenizerString Entry
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti < getTokenizerString Exit
[8/18/09 11:05:59:660 PDT] 0000000a LanguageUtili 3 Top: next: " "
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti > addOptionValue: nopreCompileJSPs Entry
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti 3 next: -distributeApp
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti < addOptionValue: Exit
[8/18/09 11:05:59:660 PDT] 0000000a LanguageUtili 3 added option value...
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti > addOptionValue: distributeApp Entry
[8/18/09 11:05:59:660 PDT] 0000000a JythonUtiliti 3 next: -nouseMetaDataFromBinary


Administrative properties for wsadmin script

Scripting administration utilizes several Java property files. Property files can be used to control your system configurations. Before any property file is specified on the command line, three levels of default property files are loaded. These property files include an installation default file, a user default file, and a properties file.

The first level represents an installation default, located in the /profile_root/properties directory for each application server profile called wsadmin.properties. The second level represents a user default, and is located in the Java user.home property. This properties file is also called wsadmin.properties. The third level is a properties file that is pointed to by the WSADMIN_PROPERTIES environment variable. This environment variable is defined in the environment where the wsadmin tool starts.

If one or more of these property files is present, they are interpreted before any properties file that is present on the command line. The three levels of property files load in the order that they are specified. The properties file that is loaded last overrides the ones loaded earlier.

This is the sample wsadmin.properties file from my machine, it has detailed description of what each of the properties mean.

#-------------------------------------------------------------------------
# Properties file for scripting client
# Cell Manager version
#-------------------------------------------------------------------------
#
#-------------------------------------------------------------------------
# The connectionType determines what connector is used.
# It can be SOAP or RMI.
# The default is SOAP.
#-------------------------------------------------------------------------
com.ibm.ws.scripting.connectionType=SOAP
#com.ibm.ws.scripting.connectionType=RMI

#-------------------------------------------------------------------------
# The port property determines what port is used when attempting
# a connection.
# The default SOAP port for a dmgr or custom profile is 8879
#-------------------------------------------------------------------------
com.ibm.ws.scripting.port=8879

#-------------------------------------------------------------------------
# The host property determines what host is used when attempting
# a connection.
# The default value is localhost.
#-------------------------------------------------------------------------
com.ibm.ws.scripting.host=localhost

#-------------------------------------------------------------------------
# The defaultLang property determines what scripting language to use.
# Supported values are jacl and jython.
# The default value is jacl.
#-------------------------------------------------------------------------
com.ibm.ws.scripting.defaultLang=jython

#-------------------------------------------------------------------------
# The echoparams property determines whether parameters or arguments are
# outputed to STDOUT or to wsadmin trace file. User can disable the property
# for security purpose to not output parameters to STDOUT or to wsadmin trace.
# The default value is true.
#-------------------------------------------------------------------------
com.ibm.ws.scripting.echoparams=true

#-------------------------------------------------------------------------
# The traceFile property determines where trace and logging
# output are directed. If more than one user will be using
# wsadmin simultaneously, different traceFile properties should
# be set in user properties files.
# The default is that all tracing and logging go to the console;
# it is recommended that a value be specified here.
# If the file name contains DBCS characters, use unicode format such as \uxxxx, where xxxx is a number
#-------------------------------------------------------------------------
com.ibm.ws.scripting.traceFile=C:/Cert/WebSphere/AppServer/profiles/Dmgr01/logs/wsadmin.traceout

#-------------------------------------------------------------------------
# The validationOutput property determines where validation
# reports are directed. If more than one user will be using
# wsadmin simultaneously, different validationOutput properties should
# be set in user properties files.
# The default is wsadmin.valout in the profile directory.
# If the file name contains DBCS characters, use unicode format such as \uxxxx, where xxxx is a number
#-------------------------------------------------------------------------
com.ibm.ws.scripting.validationOutput=C:/Cert/WebSphere/AppServer/profiles/Dmgr01/logs/wsadmin.valout

#-------------------------------------------------------------------------
# The traceString property governs the trace in effect for
# the scripting client process.
# The default is no tracing.
#-------------------------------------------------------------------------
com.ibm.ws.scripting.traceString=com.ibm.*=all=enabled

#-------------------------------------------------------------------------
# The profiles property is a list of profiles to be run before
# running user commands, scripts, or an interactive shell.
# securityProcs is included here by default to make security
# configuration easier.
#-------------------------------------------------------------------------
com.ibm.ws.scripting.profiles=C:/Cert/WebSphere/AppServer/bin/securityProcs.jacl;C:/Cert/WebSphere/AppServer/bin/LTPA_LDAPSecurityProcs.jacl

#-------------------------------------------------------------------------
# The emitWarningForCustomSecurityPolicy property controls whether
# message WASX7207W is emitted when custom permissions are found.
# Possible values are: true, false
# The default is "true"
#-------------------------------------------------------------------------
# com.ibm.ws.scripting.emitWarningForCustomSecurityPolicy=true

#-------------------------------------------------------------------------
# The tempdir property determines what directory to use for temporary
# files when installing applications.
# The default is that the JVM decides -- this is java.io.tmpdir
#-------------------------------------------------------------------------
com.ibm.ws.scripting.tempdir=c:/temp/applicationinstall

#-------------------------------------------------------------------------
# The validationLevel property determines what level of validation to
# use when configuration changes are made from the scripting interface.
# Possible values are: NONE, LOW, MEDIUM, HIGH, HIGHEST
# The default is HIGHEST
#-------------------------------------------------------------------------
com.ibm.ws.scripting.validationLevel=HIGHEST

#-------------------------------------------------------------------------
# The crossDocumentValidationEnabled property determines whether the validation
# mechanism examines other documents when changes are made to one document.
# Possible values are: true, false
# The default is true
#-------------------------------------------------------------------------
#com.ibm.ws.scripting.crossDocumentValidationEnabled=

#-------------------------------------------------------------------------
# The classpath property is appended to the list of paths to search for
# classes and resources.
# There is no default value.
#-------------------------------------------------------------------------
#com.ibm.ws.scripting.classpath=


jacl2jython utility

Both Jacl and Jython scripting languages are supported in WebSphere Application Server but JACL is deprecated and you should develop all your new wsadmin scripts using Jython. If you have existing JACL scripts then you can use the jacl2jython utility shipped with WebSPhere Application Server toolkit to convert your jacl script into jython script. This utility is meant to do most of the preliminary conversions and once the syntax conversion is done, you will have to manually verify the script to resolve problems and make sure that it is converted as per your intention. Take a look at Migrating administrative script to Jython section for further information

I tried using this this conversion utility to convert Hello World jacl script to jython by following these steps

• Create test.jacl script like this
  
puts "Hello world"

  


• Then go to <applicationservertoolkitroot>/bin folder and execute Jacl2Jython.bat c:\temp\test.jacl to convert my test.jacl into jython file


• The conversion utility creates a .py file in the same directory as that of the .jacl script, in my case it created test.py file like this
  

  
  import sys
  def wsadminToList(inStr):
          outList=[]
          if (len(inStr)>0 and inStr[0]=='[' and inStr[-1]==']'):
                  tmpList = inStr[1:-1].split(" ")
          else:
                  tmpList = inStr.split("\n")  #splits for Windows or Linux
          for item in tmpList:
                  item = item.rstrip();        #removes any Windows "\r"
                  if (len(item)>0):
                          outList.append(item)
          return outList
  #endDef
  
  print "Hello world"
  

  
  

If you search for wsadmin script samples on google most of the examples that you will find are developed using the JACL syntax so this utility comes in handy to convert those samples into jython

Enabling trace using WSAdmin Script

You can use the following WSAdmin script to enable Runtime and Server startup time trace

Runtime trace


def enableRunTimeTrace(serverName, traceString):
ts = AdminControl.queryNames("type=TraceService,process="+serverName+",*")
AdminControl.setAttribute(ts,"traceSpecification",traceString)

enableRunTimeTrace("server1","com.ibm.websphere.*=finest")


Configuration/ Server Startup Time trace



def enableConfigurationTimeTrace(serverId, traceString):
server = AdminConfig.getid('/Cell:sunpatil-wxp02Node01Cell/Node:sunpatil-wxp02Node01/Server:server1/')
print server
ts = AdminConfig.list("TraceService",server)
print ts
AdminConfig.modify(ts,[['startupTraceSpecification',traceString]])
AdminConfig.save()

enableConfigurationTimeTrace("server1","com.ibm.websphere.*=finest")


Generating thread dump/java core using WSAdmin script

You can generate Thread Dump or Java core manually using the following WSAdmin Script

def generateThreadDump(serverName):
serverJVM = AdminControl.queryNames("type=JVM,process="+serverName+",*")
AdminControl.invoke(serverJVM,"dumpThreads")

generateThreadDump("server1")


The generateThreadDump() method takes server name and generates thread dump for that server. Once the thread dump is generated you can find out the location of the thread dump from native_stderr.log file. This is sample of the messages from my native_stderr.log


JVMDUMP007I JVM Requesting Java Dump using 'C:\Cert\WebSphere\AppServer\profiles\AppSrv01\javacore.20090705.212408.5480.0001.txt'
JVMDUMP010I Java Dump written to C:\Cert\WebSphere\AppServer\profiles\AppSrv01\javacore.20090705.212408.5480.0001.txt


Setting Hang Detection policy using wsadmin script

You can set the hang detection policy using the following admin script

server = AdminControl.completeObjectName("type=Server,*")
# Print existing values of the attributes to console
print AdminControl.getAttribute(server,"threadMonitorInterval")
print AdminControl.getAttribute(server,"threadMonitorThreshold")
print AdminControl.getAttribute(server,"threadMonitorAdjustmentThreshold")

# Set new attribute values
AdminControl.setAttribute(server,"threadMonitorInterval","70")
AdminControl.setAttribute(server,"threadMonitorThreshold","70")
AdminControl.setAttribute(server,"threadMonitorAdjustmentThreshold","70")


Please note one very important point that AdminControl object is used for making changes in the runtime environment, so the changes that you make using this script would be effective immediately, and you will loose those changes if you restart the server

I could not find attribute that allows you to generate javacore on hanged thread.