Chapter 6. wsadmin

“Make it so!”

—Jean-Luc Picard, USS Enterprise-E commanding

The wsadmin program can and should be considered a scripting engine for performing administrative tasks on an application server or its configuration. It can be used to execute individual commands or multiple commands in an interactive/interpretive fashion, or it can be used to execute script files. Just as Jean-Luc Picard commands the astronauts who control the starship Enterprise, wsadmin commands and controls how WebSphere Application Server behaves and configures the way WebSphere Application Server starts.

The operating system being used defines how the wsadmin program should be executed. The examples included in this chapter show how the command to start the wsadmin program looks in a Unix® and a Windows type of environment. The ./ before the name of the file to be executed on a Unix environment is an indication that the specified file is located in the current directory. The options in square brackets is simply a notation used to indicate that user-specified options are, in fact, optional.

• AIX®—wsadmin.sh [options]

• Linux®—wsadmin.sh [options]

• z/OS®—wsadmin.sh [options]

• Windows—wsadmin¹ [options]

¹ Windows executable files extensions (e.g., .bat) are optional.

Let’s begin by looking at the wsadmin “help” (usage) information. Specifying -?, -h, or -help after wsadmin on the command line will cause wsadmin to display its help details, and terminate.

Listing 6.1 shows a significant portion of the wsadmin help, and Table 6.1 describes values that are allowed for individual options. From the number and variety of these options, it should be clear that an assortment of things can be specified on the wsadmin command line to identify and indicate what wsadmin should do for a particular invocation. Unfortunately, what may not be as easily understood are the implications of the selections that can be made or the default settings that exist and how these defaults can be changed to suit your particular needs. The purpose of this chapter is to explain these aspects of the wsadmin program.

Listing 6.1 wsadmin Help Information

Table 6.1 wsadmin Command Invocation Explained

To better understand these things, it is best to begin by describing what happens when wsadmin starts executing. Looking at the wsadmin help output, you find a number of available options. Unfortunately, the way that they are presented might make them a bit difficult to understand, but grouping the options into categories might make things a little clearer.

wsadmin Options

It’s probably a good idea to familiarize yourself with the wsadmin command-line options. Even though you may eventually get into a habit of using only a subset of these options, it is good to realize which ones exist, just in case you need to do something different.

Usage Information

The first category of options might best be called usage information or documentation. The options that fit this category are used to display the wsadmin usage details and were shown earlier.

If no command or script is specified, an interpreter shell is created for interactive use. To leave an interactive scripting session, use either the quit or exit commands.

Several commands, properties files, and profiles may be specified on a single command line. They are processed and executed in the order they are specified.

The Java Virtual Machine Initialization Phase

The wsadmin program is written in Java. It requires a Java Virtual Machine (JVM) in order to execute. So the next category of options is related to the JVM and its initialization.

-javaoption <java_option>

This option allows values to be provided that define how the JVM should be initialized. Any valid JVM option may be included. For example, to define the maximum size to be used by the Java heap, one can use something like -javaoption -Xmx1024m.

-wsadmin_classpath <classpath>

This option should be used to add Java class files to the classpath. Multiple entries should be separated using a semicolon. Should a space exist in any of the directory names, surround the entire value in double quotes. The example option, shown next, demonstrates how to add the specified archive (.jar) file to the wsadmin classpath. If you have Java libraries that you would like to add to the wsadmin code base, this is how you would do that. If you have some Java code that uses the Java Management Extensions (JMX) to monitor and control the behavior of WebSphere, this is how you would load that code into wsadmin:

-wsadmin_classpath "C:/Program Files/classes/myClasses.jar"

The wsadmin Environment Initialization Phase

The next category of options is related to the tailoring of the wsadmin environment, which in many ways is an extension of the settings used to configure the JVM environment. To better understand this, it is best to begin by explaining that some wsadmin configuration information is specified on the command line, and other information is provided using Java property files. Property files are simple text files containing directives and optional comment statements.

Comment statements are exclusively for the use of any human reader and are ignored by wsadmin. The first non-blank character on these lines is an octothorpe # or an exclamation mark!. Fortunately, the default property files contain numerous comments explaining each directive statement, the possible values to which it can be assigned, and the default value should the directive not exist.

Directive statements are of the form key=value and frequently correspond to command-line options. The keys and values found in the default property files are created either during the installation of the WebSphere Application Server product or during the creation of a profile and have a prefix of com.ibm.ws.scripting. Table 6.2 shows the property key suffix, its default value, and the corresponding command-line option (should one exist).²

² Remember that each property key begins with com.ibm.ws.scripting.

Table 6.2 wsadmin Property Keys and Command-Line Options

³ This property suffix is all one camelcase word.

It should be easy to understand that wsadmin performs its job depending on the options that are provided on the command-line. What may not be clear is that the property files exist to define “default” values should command-line options not be provided. It should be no surprise that the primary property file that is processed during the initialization of wsadmin is named wsadmin.properties. So should you decide that particular properties are appropriate for your environment, you can either modify the existing property files or create your own to reflect your individual or group needs.

Another thing that you should realize is that multiple instances of the property files exist (especially when multiple profiles exist), which brings up a major “pet peeve” with this and, unfortunately, many other products—the use of very similar terminology for different things. Specifically, the use of profile here actually refers to the profileName command-line option. If you take a moment to search the online documentation for the term “profile” or “profiles,” the vast majority of references are related to the topic of profileNames. In fact, choosing one of the first pages⁴ that is located, you find that it contains the following statement:

⁴ http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/cpro_overview.html.

“A profile defines the runtime environment. The profile includes all of the files that the server processes in the runtime environment and that you can change.”

It is not until you reach a topic entitled “Setting up profile scripts to make tracing easier using scripting” that you encounter the first reference to the command-line option identified by the -profile option. The topic of profile scripts is discussed shortly; however, first we need to finish the discussion about the profileName option, which has the misfortune of being referred to as profile in many places in the documentation. In this book, every effort is made to distinguish between the concept of profile as in profileName and profile as in profile script file.

Anyway, it may not be immediately obvious which of the property files will be used when wsadmin is executed and that values from multiple property files might be read and used during one execution of wsadmin. What determines which files are used? Determining factors can include the following:

1. Which wsadmin command script (for example, .bat or .sh) file was executed?

The answer to this question identifies that the wsadmin program, as is the case with any of the command script files provided with the WebSphere Application Server product, can, by its location, imply a “default” profileName to be used should one not be specified on the command line. For example, should the “wsadmin” command script from a particular profile bin directory (that is, ”...WebSphereAppServerprofilesAppSrv01in”) be executed, then this is exactly the same as having executed the “wsadmin” command script from the <WAS_HOME>in (for example, ”...WebSphereAppServerin”) directory and having specified "-profileName AppSrv01" as a command-line option.

2. Which profileName has been identified as the “default?”

This question is important should the “wsadmin” command script from the <WAS_HOME>in directory be executed without providing the profileName option, in which case this identifies the profileName to be used should one not be provided.

3. What wsadmin command-line options were specified?

The answer to this question is especially important because it can change the “default” behavior of wsadmin command. So regardless of the answers to the previous questions, if the profileName command-line option is specified, it takes precedence over the default profileName value. Furthermore, there is an option that allows you to specify additional property files (for example, the "-p" option, as described later).

If you don’t know or can’t remember which profileName has been defined as the default, there is an easy way to find out which will be used by the wsadmin command script. From a command prompt, execute the manageprofiles command script and specify the -getDefaultName option, as shown in the example:

...in>manageprofiles -getDefaultName
AppSrv00

Should you decide that a different profileName be used as the default for your environment, the manageprofiles command may be used to change the default, as shown in this example:

...in>manageprofiles -setDefaultName -profileName AppSrv00
INSTCONFSUCCESS: Success: The default profile has been set.

Once you have determined the profileName being used when the wsadmin starts executing, the next question to be answered is, “Which properties file(s) will be used during the initialization of wsadmin?” During its initialization, wsadmin looks for a file named wsadmin.properties in each of the following locations:

1. Below the installation root directory—For example, <WAS_HOME>profiles<profileName>propertieswsadmin.properties.

2. The user default, or home directory—For example, <USERPROFILE> wsadmin. properties.

3. The file specified by the WSADMIN_PROPERTIES environment variable (should one exist)—For example, %WSADMIN_PROPERTIES%.

What does it mean that wsadmin “looks” for a file in each of these places? If the specified file exists, any properties (for example, key=value statements) contained therein are read and saved—meaning that a key=value statement occurring in the first file found may be overridden by another occurrence of the same key in a subsequent property file. So be careful. You might need to override a property file setting with a command-line option (for example, -tracefile) and review the messages contained therein to understand exactly which properties files are loaded and in which order to understand how the initialization of the wsadmin environment occurs.

In addition to the properties files listed here, the -p command-line option can be used to specify one or more additional properties files to be loaded and processed during the initialization of wsadmin. Again, any of these files may be used to override existing key values set by any of the previously identified property files.⁵ The syntax of this command-line option is seen here:⁶ -p <properties_file_name>

⁵ Because of the potential confusion that can occur, a best practice would probably include a limitation of the number of properties files to be specified and processed as part of the initialization of wsadmin.

⁶ Remember to enclose the properties_file_name in double quotes if a space exists anywhere in the value. For example: -p "C:Program Filespropertiesmy.properties".

The wsadmin tool uses information from the property files to determine things such as:

• The default communication protocol to be used, if any

• The hostname of the default application server

• The default port number to which the connection request should be sent

• The user and password to be used for authentication.

Fortunately, the information in the property files is very well documented and easily understood. However, not all option values are identified in the comments (for example, even though NONE is a valid communication protocol, its availability is not documented in the wsadmin.properties file).

The Connection Phase

After all of the wsadmin environment property values have been loaded, the next phase of the initialization can take place. This is when wsadmin uses the connection type value to determine whether a connection to an application server should be attempted. If not, that is, should -conntype none⁷ be specified on the command line or in the property file(s), wsadmin initialization does not attempt to connect to an application server and could be used to view and manipulate the application server configuration details. When wsadmin is not connected to an application server, it is called being in local mode.

⁷ The IBM InfoCenter shows the word "NONE" in uppercase. In fact, you can use either upper- or lowercase.

If the connection type identifies that either a SOAP or RMI/IIOP connection should be established, then additional property settings are used to determine the host and port number to which the connection request should be sent. Additionally, when security is enabled on the target application server, the user and password information need to be communicated to the application server so that permission to communicate with the server can be authenticated.

The properties and/or command-line options that are used during this connection phase are as follows:

• conntype

• host

• port

• user

• password

You can choose to save the user and password authentication values in communication protocol-specific files (for example, soap.client.props or sas.client.props). However, you should be aware of the security implications of saving user and password information on your file system. Additionally, you should also be aware of the implications of providing the user and password information as wsadmin command-line options, given that it is possible to display the command-line options of any executing program on all of the operating systems on which the application server product is supported.

If security is enabled on your application server and the user and password information is not available in the property files, or as command-line options, wsadmin attempts to open a dialog box and prompt you for the user and password information.

One of the useful characteristics about the wsadmin program is the fact that it explains what it is doing, as well as what it is trying to do. For example, when wsadmin is started and is able to connect to an application server, the first line of output generated indicates the name of the server with which the connection was made (or attempted), the communication protocol that was used, and the kind of application server to which the connection was made (if the connection was successful). Listing 6.2 contains two examples of this connection message.

Listing 6.2 WASX7209I Connection Message

Defining the Scripting Language

After the connection phase, the environment initialization phase determines the scripting language using the –lang option (from either a wsadmin.properties file or a command line option).

The only valid entries are the case sensitive values jacl and jython. Because this book is only concerned with the latter, it is recommended that you locate the directive in your property file named com.ibm.ws.scripting.defaultLang and change the value from jacl to jython. Remember to also change the profile script names if you do this.⁸

⁸ If you change the language setting, it is very important to also change the names of the default profiles. See the section “wsadmin Profile Script Files” for very important details.

Trace-Related Options

Another of the things that can be controlled about the environment initialization is related to tracing. Three command-line options exist that relate to tracing of wsadmin:

• tracefile

• appendtrace

• jobid

The first two of these have corresponding settings in wsadmin.properties (for example, traceFile and appendTrace). The other (-jobid) is only available as a command-line option and is used to add a text string to the wsadmin trace file. This entry can be used to correlate the contents of the trace file with a specific invocation of wsadmin. If the jobid text string contains spaces, then the string should be enclosed in quotation marks:

wsadmin -jobid "Ports used" -f ListPorts.py

Another trace-related option is only available using wsadmin.properties file. Looking therein, you can see that, by default, this key=value is commented out, which means that a default level of tracing is selected:

AbstractShell A      JobID=Ports used

After executing this command, the trace file (wsadmin.traceout) will contain a line like that shown in the code example that follows. This can prove to be especially useful should the appendtrace option be specified, which could cause the trace messages from multiple invocations of the wsadmin tool to be contained in the trace file. This allows the section of the trace file associated with a specific wsadmin invocation to be quickly located by searching for the appropriate jobid text string:

#com.ibm.ws.scripting.traceString=com.ibm.*=all=enabled
ManagerAdmin    I      TRAS0017I: The startup trace state is *=info.

wsadmin Profile Script Files

Once the language property is set and the associated scripting portion of the wsadmin tool is initialized, the next option to come into play is associated with the processing of profile script files. These script files must be of the appropriate language, which in this case is Jython. The default property file directive for this option is shown in the code example provided here:

com.ibm.ws.scripting.profiles=.../securityProcs.jacl;
   .../LTPA_LDAPSecurityProcs.jacl

Remember to change the file extension for these profile files from .jacl to .py, and verify that the specified files exist in the indicated locations. During the initialization of wsadmin, any files specified here will be used to configure the wsadmin scripting environment before any command or script is executed.

After you’ve made that change and started an interactive wsadmin session, you can use the dir() command to find out what objects exist in the default namespace. Listing 6.3 shows an example of this. When we first encountered this information, our initial reaction was, “Wow, from where did all of these objects come?”

Listing 6.3 Default wsadmin Namespace

You might not like to have the namespace cluttered with things that you’re not planning on using. So let’s remove the default profile script files that were used by commenting out the com.ibm.ws.scripting.profiles directive in the wsadmin.properties file. After doing this, you can see that the number of items made available in the default namespace is greatly reduced. Listing 6.4 demonstrates the contents of the default Jython namespace when no profile script files are specified.

Listing 6.4 Minimum wsadmin Namespace

Because these specified files are Jython script files, you can use a text editor to find out what they are doing and how it is being done.

securityProcs.py contains definitions for these functions:

• checkuserpw()—Takes a user and password as arguments and checks with the MBean server to see if they are valid.

• securityon()—Takes a user and password as arguments and enables security.

• securityoff()—Disables security “enabled” flag.

And the other file, LTPA_LDAPSecurityProcs.py, contains all of the other items and objects that show up in the namespace in Listing 6.5. Is there an easy way to get a list of these items? Yes, first look at wsadmin.properties and the profiles directive to locate the fully qualified name of the directory containing the file. Then use the steps identified in Table 6.3 to generate this list of items, as seen in Listing 6.5. In fact, it is quite a list—32 objects in all. Granted, some of them are automatically provided by Jython ('__doc__', '__file__', and '__name__' for example), but you get the idea. If you take the time to open the script file in a text editor, you will see that half of the items are functions, and the remainder are variables.⁹

⁹ Please be careful, though. When we viewed LTPA_LDAPSecurityProcs.py in a text editor, we were very surprised to find that indentation was done using a mixture of spaces and tab characters. This is an extremely bad practice and should be avoided.

Listing 6.5 Listing a Module Namespace

Table 6.3 Listing a Module Namespace Explained

Based on this information, you can decide whether to include the securityProcs.py or LTPA_LDAPSecurityProcs.py as profile script files or not. For simplicity sake, remove these default script files from the directive. If there are circumstances when you would like to occasionally use one of these files, then you might want to consider using the -profile command-line option to do so. It allows you to add one or more profile script files without modifying your properties files.

Another use for the -profile command-line option is that it allows you to test profile script files and their contents before you decide that they are stable enough to be added to one of the wsadmin.properties files. It is easy to create a profile script file containing a function to be tested. Then this script file can be defined and loaded using the -profile command-line option and thoroughly tested using an interactive wsadmin session. When you’re confident that the function works as you want it to, you can either move the function to an existing profile script file or simply add this file to the list of profile script files in the profiles directive in the appropriate wsadmin.properties file.

Commands and Script Files

The last group of wsadmin command-line options are related to script files, or commands. Let’s first take a look at the -c wsadmin command-line option, which is used to execute one or more commands. To execute multiple commands, you can either specify each with a -c option, or you can use a semi-colon (line separator) between the statements. Because it is very likely that the command(s) to be executed will contain one or more spaces, it is very likely that you will need to surround the command(s) to be executed by double quotation marks, as shown in Listing 6.6.

Listing 6.6 Specifying Multiple Commands

After all of the commands that have been specified using this option have been executed, the wsadmin program exits gracefully and automatically commits any configuration changes you have made. This is exactly the same effect as adding AdminConfig.save() immediately after your command.

Thinking quickly about this might make you wonder whether this has any value at all. The reason for this concern is the fact that there is a non-trivial amount of overhead related to starting up a wsadmin session, and if all you are going to do is have a single command executed, why bother? Well, the answer to that question is yes; there is some overhead associated with using the -c command-line option to execute a single, or even a few, wsadmin command(s). However, there are times when this technique can do exactly what you need it to do. Additionally, there are times when the output of a single command can be voluminous, in which case, using the -c command-line option to execute this command allows you to redirect the output of a command to a file for later review.

Because we have yet to discuss any of the administrative objects, it is a little difficult to provide a good example for this option. However, Listing 6.7 shows an example that should be easily understood. It shows how a method (reportConfigInconsistencies(), for example) of an administrative object (AdminTask) can be invoked, and the return value of this call (a string) can be display using a print statement. It should be fairly clear from both the name of the method and the generated output what this particular statement does.

Listing 6.7 Example Use of -c <command>

The final command-line option to be discussed is -f, and is used to specify a Jython script file to be executed. If you execute the wsadmin command from the directory containing the script file, then you don’t have to include any path or directory references as part of the -f option. For example, let’s look at this code:

C: emp>set WAS_HOME=C:IBMWebSphereAppServer
C: emp>%WAS_HOME%inwsadmin -conntype none -f ListPorts.py

If the fully-qualified path to the script file contains spaces, then this parameter should be enclosed in double quotes, as shown:

wsadmin -f "C:Program FilesscriptsListPorts.py"

Another thing shown in the wsadmin usage information is something like [script parameters]. This simply means that anything specified on the wsadmin command line that is not recognized as a wsadmin command-line option is made available to the script. For Jython scripts, parameters are made available via the sys.argv list. Listing 6.8 shows how to specify script parameters and how they can be accessed using sys.argv data structure. It also shows how the parameters are identified as unrecognized wsadmin options and are therefore being passed on to the scripting environment. This topic was discussed in the section “getopt() Module” in Chapter 5, “Jython Modules.”

Listing 6.8 Script Parameters and sys.argv

Interactive/Interpretive wsadmin Session

Each of the following options causes wsadmin to exit after performing requested function:

• help (or -?)

• c <command>

• f <script_file>

If one of these options is not specified, the wsadmin scripting environment is initialized, and a “command prompt” (for example, wsadmin>) is displayed to indicate that wsadmin is awaiting user input to determine what needs to be done. You have seen examples of this previously.

An interactive wsadmin session can be a very useful and educational experience. The immediate response to the user input allows for code fragments to be entered and tested for syntax errors, as well as logic error. It can also be used to interact with administrative objects to learn about the application server configuration and the commands used to manipulate it.

Should you later determine that the interactive session would be useful as a function, you can make use of the fact that the commands that were executed are automatically written to the wsadmin trace file (identified by the traceFile directive in a properties file or by the –traceFile command-line option). It requires some editing on your part to extract the useful commands into a function, but it is certainly worth knowing that the commands that were executed are written somewhere should you need them.

Summary

wsadmin is a command shell. This chapter showed some different ways in which the wsadmin environment can be configured, including the Java Virtual Machine used by wsadmin. We also saw some configuration information that may be used to control wsadmin and its access to an enterprise security service. Finally, we showed you the mechanics of using the wsadmin command shell. In the chapters that follow, we see how to use the scripting objects that exist within the wsadmin environment.