Wsadmin

The wsadmin tool is a command shell for the purpose of performing systems administration on all the artifacts in an IBM WebSphere Application Server (WAS) cell. It gets its name from the name of the shell script that invokes this command shell. This command shell can execute connected to a WAS cell or completely disconnected from a WAS cell (local mode). The wsadmin tool can be used to execute scripts written in Jacl and Jython, or it can be used interactively to execute individual commands. These scripts and commands perform administrative tasks like application deployment, configuration changes and run-time monitoring and control of IBM WAS.

History of WebSphere Application Server command shells

The wscp stands for WebSphere Control Program. It was used in older versions of WAS like Version 4.0 and Version 3.5. The wsadmin command shell replaced wscp in WebSphere Application Server Version 5.0 and all subsequent versions. It can perform almost all of the tasks which can be done through the browser based administrative console, and it can perform some tasks that the administrative console cannot do.

Invoking wsadmin

There is a copy of the shell script that executes wsadmin in the bin directory of WAS install root and in the bin directory of every profile. With the exception of stand alone installations of WAS, wsadmin is almost always invoked from the bin directory of the deployment manager's profile. To invoke wsadmin in interactive mode,

1. Open the command line window of the machine in which IBM WebSphere Application Server is already installed.
2. Change directory to: <IBM WebSphere Profile Path>/bin/ (This will almost always be the bin directory of the deployment manager's profile)
3. Execute the file named wsadmin.[sh | bat] . See invocation syntax for available options.
4. You will see a wsadmin command line. Any commands you type will execute immediately. If you make configuration changes, those changes will not take effect unless you invoke the save command of the AdminConfig script object.

Invocation syntax

After invocation of wsadmin the command-line window will show the following text:

wsadmin [-h(help)] [-?] [-c <commands>] [-p <properties_file_name>] [-profile <profile_script_name>] [-profileName <profile_name>] [-f <script_file_name>] [-javaoption java_option] [-lang language] [-wsadmin_classpath classpath] [-conntype SOAP [-host host_name] [-port port_number] [-user userid] [-password password] RMI [-host host_name] [-port port_number] [-user userid] [-password password] NONE]

Options

The text written between squared brackets ([...]) are called options of the wsadmin tool.

• -? is used to get help for the particular syntax.
• -c assigns to run a command, there may be more than one -c exist for multiple command assignments.
• -p describes the Java properties file.
• -profile denotes a profile script. It executes before the command. For example, first the profile script would run then the -c runs.
• -profileName denotes the name of profile for which the wsadmin tool would run. This will help to access the wsadmin tool of a profile other than the profile you are currently in.
• -f assigns name of a script. The -f must be used once.
• -javaoption designates a Java non-standard or standard option. The -javaoption could be more than one.
• -lang specifies scripting language. It may be jacl or jython.
• -wsadmin_classpath is used to assign additional classes for scripting operation.
• -conntype assigns connection type. It may be SOAP, RMI or NONE.

     *If SOAP or RMI, then give relevant host_name, port_number, userid and password.
     *If NONE, then it will run in local mode.

• -jobid is used for keeping track of invocation of wsadmin. It is situated at the beginning of wsadmin log file.
• -tracefile assigns log file name and location for the log output.
• -appendtrace: If true, then it will append the trace at the end of a log file. If false, then it will override the log file for the invocation of wsadmin.

Five script objects of wsadmin

Five script objects provide the commands that administrators execute to perform various administrative operations. Two of these - AdminControl and AdminConfig - are primitive objects. Two others - AdminApp, AdminTask - provide a more high level interface for administrative tasks. The final script object - Help - provides several different forms of help.

• AdminControl is a primitive script object that is used for operational control of all of the different kinds of running objects throughout an IBM WAS cell. AdminControl interfaces with MBeans (for Managed Bean) in order to do its job. It is used to start or stop servers, to initiate synchronization with the master repository, to purge connection pools, to interface with diagnostic providers, and many other monitor and control tasks. The AdminControl object is not available when wsadmin is run in local mode. Because MBeans only exist for running artifacts, AdminControl can only control running artifacts on servers that have started.
• AdminConfig is a primitive script object that changes WAS configuration. As of WAS version 7, there are just under 800 different pieces of configuration data that AdminConfig can create, modify, or delete. Creating a new JAAS alias, and creating or modifying a WebSphere variable are examples of things AdminConfig can do. Even though this script object has unlimited access to all WAS configuration, its use is discouraged for a variety of reasons. AdminConfig provides such a primitive interface to the WAS configuration tree that it is easy to make a mistake that can be very difficult to troubleshoot. Administrators are strongly encouraged to use AdminApp for application related administration and AdminTask for all other administrative tasks. The AdminConfig script object is available in local mode and you can use AdminConfig even if all servers in your cell are stopped.
• AdminApp provides commands for installing, uninstalling, and modifying the configuration of applications. Almost all of its commands are available in local mode and you can use AdminApp even if all servers in your cell are stopped.
• AdminTask was first documented in IBM WAS V6.1 although its use has been observed as early as version 5. Its 1130 commands (as of WAS version 7) provide a higher level interface to WebSphere Application Server administration. Although the sheer number of commands is daunting, there are many tasks, such as creating an application server, creating or modifying a cluster, and creating a message bus that can be performed with one line of AdminTask commands. Using AdminConfig for the same tasks would require several lines of tedious script. There is even a procedure for creating your own AdminTask commands should you so desire.
• Help, as the name suggests, provides several categories of help. It can provide help for each command of each script object and it can provide help for the methods, attributes and notifications of MBeans.

Two Modes of wsadmin

The wsadmin could be operated by two modes; a Remote mode and a Local mode.

• Use: The Remote mode is used when IBM WAS's Deployment Manager (Dmgr) is running. The Local Mode is used when the server is in down status.
• How to enable: The Remote mode is connected through TCP network connection while the Local mode does not need TCP connection.
• Advantages:
  • Remote mode: It can be accessed from the same or other LPAR. Two Remote mode clients will never face conflict. Their respective changes will be intellectually handled by the IBM WAS.
  • Local mode: It would not have any problems related to SSL certificates. It can work even when the server is down.
• Disadvantages:
  • Remote mode: The IBM WAS must not be in down status. There may be an issue of SSL certifications conflict.
  • Local mode: It will not work efficiently with multiple access because in the multiple access through Local mode the synchronization of changes may create a serious issue. The Local mode is weaker than Remote mode in respect of the security.

Scripting languages: Jacl and Jython

The wsadmin supports Jacl^[1] (an alternate implementation of TCL written in Java) and Jython (Java, Python) scripting languages. The choice of Jacl or Jython may depend on the programmer's comfort level. The Java/Java EE or C programmer may be more comfortable with Jython whereas Tcl experts may prefer Jacl. Though the script syntax is different, Jacl and Jython are equally powerful. The IBM Jacl to Jython Conversion Assistant program is used to convert wsadmin Jacl scripts into Jython.

Changing default language

In IBM WebSphere Application Server Version 6.1, the Jacl is deprecated. To use Jython as the scripting language, either of the two following ways.

• You may mention Jython in the option -lang of wsadmin invocation syntax. This is not a permanent change because it remains effective for that particular session only. As the wsadmin invoked again it will take Jacl as a scripting language.
• The other way is, to change default language as the Jython instead of Jacl.

To change default language, consider the following steps: (It is for Unix based systems.)

• Be in the following directory: <IBM WebSphere Profile Path>/DeploymentManager/profiles/properties
• Edit the file wsadmin.properties
• open it and you will find: com.ibm.ws.scripting.defaultLang=jacl. Just write jython instead of jacl.
• FTP that modified file and the changing default language is completed.
• Keep in mind that this method would change scripting language permanently to Jython.

Basic difference between Jacl and Jython syntaxes

Here, five basic commands (for getting help for the relevant objects) are written in their particular syntaxes. The case-sensitiveness in the scripting must be the crucial thing to be taken care of.

Jacl	Jython
puts $Help help	print Help.help()
puts $AdminConfig help	print AdminConfig.help()
puts $AdminTask help	print AdminTask.help()
puts $AdminControl help	print AdminControl.help()
puts $AdminApp help	print AdminApp.help()

Proficiency in scripting

Points to keep in mind

• The case-sensitiveness of the script syntax.
• It is a good practice to assign commands in a script and run that script using wsadmin -f <scriptfile> rathen than running each commands individually using wsadmin -c <command>. So, prefer wsadmin -f <scriptfile> to get faster execution.
• Any configuration changes that your scripts make will not take effect until you commit those changes. Use the command, AdminConfig.save ( ) (If Jython is used.) or $AdminConfig save (If Jacl is used.), to make your configuration changes permanent.

Tips / Gotchas / Limitations in wsadmin

• Jacl behaviour

Multiple nested statements inside [] cannot directly be used unless assigned to a variable

• Jython behaviour

print() statements are needed to interpret and/or convert formatting of output

References

1. http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.express.doc/info/exp/ae/cxml_jacl.html

External links

• WebSphere Application Server v6.1 Documentation
• WebSphere Application Server v7 Documentation
• WebSphere Application Server v8 Documentation
• WebSphere Application Server Administration using Jython