Wsadmin tool


 

+

Search Tips   |   Advanced Search

 

The wsadmin tool runs scripts. Use wsadmin to manage appserver as well as the configuration, application deployment, and server runtime operations.

All users who run commands from a specific profile must have authority to modify files that are created by other users that use the same profile. Otherwise, we might see a permission denied error in the log files. To avoid this issue, consider one of the following policies:

The options for wsadmin are case insensitive. Do not pass in empty strings in place of command options. The wsadmin tool displays general help information if we specify an empty string as the command option. Use the following command-line invocation syntax for the wsadmin scripting client: 

 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 user ID] [-password password] 
        [-conntype JSR160RMI [-host host_name] [-port port_number] [-user user ID] [-password password] 
        [-conntype RMI [-host host_name] [-port port_number] [-user user ID] [-password password] 
        [-conntype IPC [-ipchost host_name] [-port port_number] [-user user ID] [-password password]
        [-jobid string] 
        [-tracefile trace_file] 
        [-appendtrace true/false] 
        [script parameters]

The element, script parameters, represents any argument other than the ones listed previously. The argc variable contains the number of arguments, and the argv variable contains a list of arguments in the order that they were coded.

 

Options

-c

Specifies to run a single command. Multiple -c options can exist on the command line. They run in the order that you designate.If we invoke wsadmin with the -c option, any changes that you make to the configuration are saved automatically then. If we make configuration changes and we are not using the -c option, then use the save command of the AdminConfig object to save the changes. Read about saving configuration changes with wsadmin for more information.

-f

Script to run.

Only one -f option can exist on the command line.

Use the -f option to run scripts that contain nested Jython scripts. In the following example, the test2 script imports the test1 script:

#test1.py
def listServer():
print AdminConfig.list("Server")

#test2.py
import test1
test1.listServer()

To run the caller script, run the following command from the install_root/bin directory:

wsadmin -lang jython -f test2.py

After the scripts run, the system returns the following sample command output:

server1(cells/myCell/nodes/myNode/servers/myServer|server.xml#Server_1183122130078)

-javaoption

Specifies a valid Java standard or a non-standard option. Multiple -javaoption options can exist on the command line.

To shorten the length of the command, type the command in the following way:

wsadmin -javaoption "java_option java_option"
instead of the:

wsadmin -javaoption java_option -javaoption java_option

-lang

Language of the script file, the command, or an interactive shell. The possible languages include: Jacl and Jython. The options for the -lang argument include: jacl and jython.

This option overrides language determinations that are based on a script file name, a profile script file name, or the com.ibm.ws.scripting.defaultLang property. The -lang argument has no default value.

If we do not specify the -lang argument but we have the -f script_file_name argument specified, then wsadmin determines the language based on a target script file name. If we do not specify the -lang argument and the -f argument, wsadmin determines the language based on a profile script file name if the -profile profile_script_name argument is specified. If the command line or the property does not supply the script language, and wsadmin cannot determine it, then an error message is generated.

-p

Properties file.

The file listed after -p, represents a Java properties file that the scripting process reads. Three levels of default properties files load before the properties file specified on the command line.

  • Installation default...

    WAS_HOME/properties/wsadmin.properties

  • User default...

    $HOME/wsadmin.properties

  • Vaue of environment variable WSADMIN_PROPERTIES

Multiple -p options can exist on the command line. Those options invoke in the order that you supply them.

We can also use the custom property...

com.ibm.ws.scripting.noechoParamNo

...which enables you to specify script parameters that you not want to be visible in a trace file or standard output.

To enable this custom property, create a text file such as noecho.prop.

In this text file, specify positions within the wsadmin command that contains sensitive data, such as passwords, which do not want to see in a trace file or standard output. The text file can contain a single number or multiple parameter numbers that are separated by a comma. For example, the text file might contain the following information:

com.ibm.ws.scripting.noechoParamNo=3,5

When you reference this text file in the wsadmin command, the third and fifth parameter values do not show in a trace file or standard output. To use the custom property, run the wsadmin command and pass the text file with the -p option. For example:

Jacl...

wsadmin -f script_file script_arguments -p text_file

Jython...

wsadmin -lang jython -f script_file script_arguments -p text_file

For example:

wsadmin -f c:/text.py server1 dbuser dbpassword user1 userpassword -p c:/noecho.prop

[AIX] [HP-UX] [Linux] [Solaris]

wsadmin -f c:\text.py server1 dbuser dbpassword user1 userpassword -p c:\noecho.prop
where dbpassword and userpassword are the third and fifth parameters that are not visible in a trace file or standard output.

-profile

Profile script.

The profile script runs before other commands, or scripts. If we specify -c, then the profile script runs before it invokes this command. If we specify -f, then the profile script runs before it runs the script. In interactive mode, we can use the profile script to perform any standard initialization that you want. We can specify multiple -profile options on the command line, and they invoke in the order that you supply them.

-profileName

Profile from which wsadmin runs. Specify this option if one the following reasons apply:

  • You run wsadmin from the WAS_HOME/bin directory, and you do not have a default profile, or you want to run in a profile other than the default profile.

  • we are currently in a profile bin directory but want to run wsadmin from a different profile.

    WAS running on z/OS platforms does not support user-created profiles; only the default profile is used.

-?

Provides syntax help.

-help

Provides syntax help.

-conntype

Type of connection to use.

This argument consists of a string that determines the type, for example, SOAP, and the options that are specific to that connection type. Possible types include: SOAP, RMI, JSR160RMI, IPC and NONE.

For each connection type, we can specify additional attributes about the connection.

For the SOAP connection type, we can specify the following attributes:


Table 1. -conntype SOAP connection type attribute descriptions

Attribute Description
[-host host_name] Host name for the connection.
[-port port_number] Port number for the connection.
[-user userid] User ID to use to establish the connection.
[-password password] to use to establish the connection.

For the RMI connection type, we can specify the following attributes:


Table 2. -conntype RMI connection type attribute descriptions

Attribute Description
[-host host_name] Host name for the connection.
[-port port_number] Port number for the connection.
[-user userid] User ID to use to establish the connection.
[-password password] to use to establish the connection.

For the JSR160RMI connection type, we can specify the following attributes:


Table 3. -conntype JSR160RMI connection type attribute descriptions

Attribute Description
[-host host_name] Host name for the connection.
[-port port_number] Port number for the connection.
[-user userid] User ID to use to establish the connection.
[-password password] to use to establish the connection.

For the IPC connection type, we can specify the following attributes:


Table 4. -conntype IPC connection type attribute descriptions

Attribute Description
[-ipchost host_name] Host name for the connection. This attribute overrides the host name specified for the com.ibm.ws.scripting.ipchost property in the wsadmin.properties properties file.
[-port port_number] Port number for the connection.
[-user userid] User ID to use to establish the connection.
[-password password] to use to establish the connection.

Use the -conntype NONE option to run in local mode. The result is that the scripting client is not connected to a running server. We can manage server configuration, the installation and the uninstallation of applications without the appserver running.

Deprecated feature: You should eventually switch from the Remote Method Invocation (RMI) connector to the JSR160RMI connector because support for the RMI connector is deprecated.

-wsadmin_classpath

Use this option to make additional classes available to the scripting process.

Use the following option with a class path string:

c:/MyDir/Myjar.jar;d:/yourdir/yourdir.jar

The class path is then added to the class loader for the scripting process.

You can also specify this option in a properties file used by wsadmin. The property is com.ibm.ws.scripting.classpath. If we specify -wsadmin_classpath on the command line, the value of this property overrides any value specified in a properties file. The class path property and the command-line options are not concatenated.

-host

Specify a host name to which wsadmin attempts to connect. The default wsadmin.properties file located in the properties directory of each profile provides localhost as the value of the host property, if this option is not specified.

-password

Specify a password to be used by the connector to connect to the server, if security is enabled in the server.

On UNIX systems, the use of -password option might result in security exposure as the password information becomes visible to the system status program such as ps command which can be invoked by another user to display all the running processes. Do not use this option if security exposure is a concern. To avoid exposure, we can:

  • Specify user and password information in the soap.client.props file for the SOAP connector, sas.client.props for the JSR160RMI connector or the Remote Method Invocation (RMI) connector, or the ipc.client.props file for the IPC connector. The soap.client.props, sas.client.props, and ipc.client.props files are located in the properties directory of the appserver profile.

  • Wait for wsadmin to prompt the user for login information instead of providing the login information within a properties file.

-user or -username

Specifies a user name to be used by the connector to connect to the server if security is enabled in the server.

-port

Port to be used by the connector. The default wsadmin.properties file located in the properties directory of each appserver profile provides a value in the port property to connect to the local server.

-jobid

Specifies a jobID string so that we can keep track of each invocation of wsadmin for auditing purposes. The jobID string (jobID=xxxx) is displayed at the beginning of the wsadmin log file.

-tracefile

Name of the log file and location where the log output is directed. This option overrides the com.ibm.ws.scripting.traceFile property in the wsadmin.properties file.

-appendtrace

Determines if a trace appends to or overrides the end of the existing log file. Specify true to append the trace to the end of a log file or specify false to override the log file for each wsadmin invocation. The default value is false.

The following example specifies the jobID option, log location and appends the trace to the log file.

wsadmin -jobid wsadmin_test_1 -tracefile c:/temp/wsadmin_test_1.log -appendtrace true

 

Example

In the following syntax examples, mymachine is the name of the host in the wsadmin.properties file specified by the com.ibm.ws.scripting.port property:

SOAP connection to the local host

Use the options defined in the wsadmin.properties file.

SOAP connection to the mymachine host

Use Jacl, enter the following example code:

wsadmin -f test1.jacl -profile setup.jacl -conntype SOAP -port mymachinesoapportnumber -host mymachine

Jython...

wsadmin -lang jython -f test1.py -profile setup.py -conntype SOAP -port mymachinesoapportnumber -host mymachine

Initial and maximum Java heap size

Jacl...

wsadmin -javaoption -Xms128m -Xmx256m -f test.jacl

Jython...

wsadmin -lang jython -javaoption -Xms128m -Xmx256m -f test.py

JSR160RMI connection with security

Jacl...

wsadmin -conntype JSR160RMI -port JSR160rmiportnumber -user userid -password password

Jython...

wsadmin -lang jython -conntype JSR160RMI -port JSR160portnumber -user userid -password password

The element, rmiportnumber, for your connection is displayed in the admin console as BOOTSTRAP_ADDRESS.

On UNIX systems, the use of -password option might result in security exposure as the password information becomes visible to the system status program such as ps command which can be invoked by another user to display all the running processes. Do not use this option if security exposure is a concern. To avoid exposure, we can:

  • Specify user and password information in the soap.client.props file for the SOAP connector, sas.client.props for the JSR160RMI connector or the Remote Method Invocation (RMI) connector, or the ipc.client.props file for the IPC connector. The soap.client.props, sas.client.props, and ipc.client.props files are located in the properties directory of the appserver profile.

  • Wait for wsadmin to prompt the user for login information instead of providing the login information within a properties file.

RMI connection with security

Jacl...

wsadmin -conntype RMI -port rmiportnumber -user userid -password password

Jython...

wsadmin -lang jython -conntype RMI -port rmiportnumber -user userid -password password

The element, rmiportnumber, for your connection is displayed in the admin console as BOOTSTRAP_ADDRESS.

On UNIX systems, the use of -password option might result in security exposure as the password information becomes visible to the system status program such as ps command which can be invoked by another user to display all the running processes. Do not use this option if security exposure is a concern. To avoid exposure, we can:

  • Specify user and password information in the soap.client.props file for the SOAP connector, sas.client.props for the JSR160RMI connector or the Remote Method Invocation (RMI) connector, or the ipc.client.props file for the IPC connector. The soap.client.props, sas.client.props, and ipc.client.props files are located in the properties directory of the appserver profile.

  • Wait for wsadmin to prompt the user for login information instead of providing the login information within a properties file.

Local mode of operation to perform a single command

Jacl...

wsadmin -conntype NONE -c "$AdminApp uninstall app"

Jython...

wsadmin -lang jython -conntype NONE -c "AdminApp.uninstall('app')"



Subtopics

wsadmin tool performance tips

 

Related tasks


Saving configuration changes with wsadmin
Starting the wsadmin scripting client