wsadmin scripting tool
The wsadmin tool runs scripts. You can use the wsadmin tool to manage application servers as well as the configuration, application deployment, and server runtime operations.
You can run wsadmin commands from WebSphere® Application Server on a distributed platform and use that distributed command to administer WebSphere Application Server on a z/OS operating system.
- Use specific profiles for distinct user authorities.
- Use a separate installation for distinct user authorities.
- The same user must run all commands in a profile.
- Ensure that all users of a specific profile belong to the same group. In addition, ensure that each user of a group has the read and write authority to the files that are created by other members in the same profile.
- You must enter the wsadmin commands in the wsadmin interactive shell on one line. That is, type the command continuously and do not split the command into multiple lines. Splitting a long wsadmin command into multiple lines is not supported. Trying to run wsadmin commands that are split into multiple lines in the wsadmin interactive shell results in a syntax error.
- The wsadmin tool removes any leading and trailing space including
\n
,\r
,\t
,\f
and space when parsing a string to avoid any user errors. For example, someone might accidentally hit the spacebar key or the Tab key and add extra space to the command string. This extra space might cause the command or script to failure. If you need to include extra space in a command, either use the list syntax instead of the string syntax or enclose the string containing the extra space within[ ]
(brackets).
Use the following command-line invocation syntax for the wsadmin scripting client:
wsadmin [-h(help)]
wsadmin.sh [-h(help)]
[-?]
[-c command]
[-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]
[-conntype RMI [-host host_name] [-port port_number] [-user userid] [-password password]
[-conntype JSR160RMI [-host host_name] [-port port_number] [-user userid] [-password password]
[-conntype IPC [-ipchost host_name] [-port port_number] [-user userid] [-password password]
[-jobid 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. The -c option must be followed by a command. Multiple -c
options can exist on the command line. They run in the order that you designate.
If you invoke the wsadmin tool with the -c option, any changes that you have made to the configuration are then saved automatically. If you make configuration changes and you are not using the -c option, then you must use the save command of the AdminConfig object to save the changes. Read about saving configuration changes with the wsadmin tool for more information.
- -Dwsadmin.script.libraries=dir1;dir2;...
- Specifies the search path for Jython scripts that use packages. dir1 and dir2 represent the directory search paths for libraries containing the Jython packages.
- -f
- Specifies a script to run. The -f option must be followed by a file name.
Only one -f option can exist on the command line.
You can 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 app_server_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.
wsadmin -javaoption java_option -javaoption java_option
wsadmin.sh -javaoption java_option -javaoption java_option
To shorten the length of the command, you can type the command in the following way:
wsadmin -javaoption "java_option java_option"
wsadmin.sh -javaoption "java_option java_option"
For transitioning users: You cannot use thewsadmin -javaoption "java_option java_option"
shortened command. You must use the longerwsadmin.sh -javaoption java_option -javaoption java_option
format. Unlike previous versions, the Version 8 product does not support multiple Java options together in one-javaoption
option on Windows operating systems.On Windows operating systems, if the option contains an equal sign (=
) or a semicolon (;
), you must put double-quotation marks ("
) around the option; for example:
Windows operating systems treat the equal sign (wsadmin -javaoption "-Da.b.c=3"
=
) or the semicolon (;
) in command-line arguments as a blank space. The wsadmin tool requires arguments that have a blank space to be enclosed in double-quotation marks.For transitioning users: For WebSphere Application Server Version 8.5, the %javaoption% in wsadmin.bat and $javaOption in wsadmin.sh are located at the end of JAVA_EXE arguments. This allows you to override Java system properties, such as CLIENTSOAP and CLIENTSAS properties. - -lang
- Specifies the language of the script file, the command, or an interactive shell. The possible
languages include: Jacl and Jython. These language options are expressed as
jacl
andjython
.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 the language specified in the -lang argument does not match the language determined by in the -f script_file_name argument, then the wsadmin tool determines the language based on the script file name.If you do not specify the -lang argument but you have the -f script_file_name argument specified, then the wsadmin tool determines the language based on a target script file name. If you do not specify the -lang argument and the -f argument, the wsadmin tool 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 the wsadmin tool cannot determine it, then an error message is generated.
- -p
- Specifies a properties file. The -p option must be followed by a file name.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 that you specified on the command line:
- The first level is the installation default, wsadmin.properties, which is located in the product properties directory.
- The second level is the user default, wsadmin.properties, which is located in your home directory.
- The third level is the properties file to which the environment variable WSADMIN_PROPERTIES references.
Multiple -p options can exist on the command line. Those options invoke in the order that you supply them.
You can also use thecom.ibm.ws.scripting.noechoParamNo
custom property with this option. Use this custom property to specify script parameters that you do not want to be displayed in a trace file or standard output. To enable this custom property, create a text file such asnoecho.prop
. In this text file, specify positions within your wsadmin command that contain sensitive data, such as passwords, which you do not want to be displayed 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:
When you reference this text file in your wsadmin command, the third and fifth parameter values are not displayed 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:com.ibm.ws.scripting.noechoParamNo=3,5
Using Jacl:wsadmin -f script_file script_arguments -p text_file
Using Jython:wsadmin -lang jython -f script_file script_arguments -p text_file
For example:
wsadmin -f text.py server1 dbuser dbpassword user1 userpassword -p noecho.prop
wsadmin -f c:/text.py server1 dbuser dbpassword user1 userpassword -p c:/noecho.prop
wsadmin.sh -f text.py server1 dbuser dbpassword user1 userpassword -p noecho.prop
dbpassword
anduserpassword
are the third and fifth parameters that are not displayed in a trace file or standard output. - -profile
- Specifies a profile script.
The profile script runs before other commands, or scripts. If you specify -c, then the profile script runs before it invokes this command. If you specify -f, then the profile script runs before it runs the script. In interactive mode, you can use the profile script to perform any standard initialization that you want. You can specify multiple -profile options on the command line, and they are invoked in the order that you specify them.
- -profileName
- Specifies the profile from which the wsadmin tool runs. Specify this option if one the following
reasons apply:
- You run the wsadmin tool from the app_server_root/bin directory, and you do not have a default profile, or you want to run in a profile other than the default profile.
- You are currently in a profile bin directory but want to run the wsadmin
tool from a different profile.Important: WebSphere Application Server running on z/OS operating systems does not support user-created profiles; only the default profile is used.
- -?
- Provides syntax help.
- -help
- Provides syntax help.
- -conntype
- Specifies the 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, you can specify additional attributes about the connection.
For the SOAP connection type, you can specify the following attributes:Table 1. -conntype SOAP connection type attribute descriptions. Use this attribute to specify a SOAP connection type. Attribute Description [-host host_name] Specifies the host name for the connection. The default is the local host. [-port port_number] Specifies the port number for the connection. [-user userid] Specifies the user ID to use to establish the connection. [-password password] Specifies the password to use to establish the connection. For the RMI connection type, you can specify the following attributes:Table 2. -conntype RMI connection type attribute descriptions. Use this attribute to specify an RMI connection type. Attribute Description [-host host_name] Specifies the host name for the connection. The default is the local host. [-port port_number] Specifies the port number for the connection. [-user userid] Specifies the user ID to use to establish the connection. [-password password] Specifies the password to use to establish the connection. For the JSR160RMI connection type, you can specify the following attributes:Table 3. -conntype JSR160RMI connection type attribute descriptions. Use this attribute to specify a JSR160RMI connection type. Attribute Description [-host host_name] Specifies the host name for the connection. [-port port_number] Specifies the port number for the connection. [-user userid] Specifies the user ID to use to establish the connection. [-password password] Specifies the password to use to establish the connection. For the IPC connection type, you can specify the following attributes:Table 4. -conntype IPC connection type attribute descriptions. Use this attribute to specify an IPC connection type. Attribute Description [-ipchost host_name] Specifies the 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] Specifies the port number for the connection. [-user userid] Specifies the user ID to use to establish the connection. [-password password] Specifies the 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. You can manage server configuration, the installation and the uninstallation of applications without the application server 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 your scripting process.
Use the following option with a class path string:
/MyDir/Myjar.jar;/yourdir/yourdir.jar
/home/MyDir/Myjar.jar;/yourdir/yourdir.jar
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 that is used by the wsadmin tool. The property is com.ibm.ws.scripting.classpath. If you specify -wsadmin_classpath on the command line, the value of this property overrides any value that is 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.Attention: On UNIX systems, the use of -password option might result in security exposure because the password information is displayed in the system status program. For example, this information might be exposed when you use the ps command, which can be invoked by another user to display all running processes. Do not use this option if security exposure is a concern. To avoid exposure, you can:
- Specify user and password information in the soap.client.props file for the SOAP connector, the sas.client.props file for the JSR160RMI connector or the Remote Method Invocation (RMI) connector, or the ipc.client.props file for the Inter-Process Communications (IPC) connector. The soap.client.props, sas.client.props, and ipc.client.props files are located in the properties directory of your application server profile.
- Wait for the wsadmin tool 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
- Specifies a port to be used by the connector. The default wsadmin.properties file located in the properties directory of each application server profile provides a value in the port property to connect to the local server.
- -jobid
- Specifies a job ID string so that you can keep track of each invocation of the wsadmin tool for auditing purposes. The jobI D string (jobID=xxxx) is displayed at the beginning of the wsadmin log file.
- -tracefile
- Specifies the 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 job ID option, log location and appends the trace to the log file.
wsadmin -jobid wsadmin_test_1 -tracefile /temp/wsadmin_test_1.log -appendtrace true
wsadmin -jobid wsadmin_test_1 -tracefile c:/temp/wsadmin_test_1.log -appendtrace true
wsadmin.sh -jobid wsadmin_test_1 -tracefile /temp/wsadmin_test_1.log -appendtrace true
In the following syntax examples, mymachine is the name of the host in the wsadmin.properties file that is specified by the com.ibm.ws.scripting.port property:
SOAP connection to the local host
Use the options that are defined in the wsadmin.properties file.
SOAP connection to the mymachine host
Using Jacl, enter the following example code:wsadmin -f test1.jacl -profile setup.jacl -conntype SOAP
-port mymachine_soap_portnumber -host mymachine
wsadmin.sh -f test1.jacl -profile setup.jacl -conntype SOAP
-port mymachine_soap_portnumber -host mymachine
Using Jython:
wsadmin -lang jython -f test1.py -profile setup.py -conntype
SOAP -port mymachine_soap_portnumber -host mymachine
wsadmin.sh -lang jython -f test1.py -profile setup.py -conntype
SOAP -port mymachine_soap_portnumber -host mymachine
Change initial and maximum Java heap size
Using Jacl:
wsadmin -javaoption -Xms128m -javaoption -Xmx256m -f test.jacl
wsadmin -javaoption "-Xms128m -Xmx256m" -f test.jacl
orwsadmin -javaoption -Xms128m -javaoption -Xmx256m -f test.jacl
wsadmin.sh -javaoption "-Xms128m -Xmx256m" -f test.jacl
Using Jython:
wsadmin -lang jython -javaoption -Xms128m -javaoption -Xmx256m -f test.py
wsadmin -lang jython -javaoption "-Xms128m -Xmx256m" -f test.py
orwsadmin -lang jython -javaoption -Xms128m -javaoption -Xmx256m -f test.py
wsadmin.sh -lang jython -javaoption "-Xms128m -Xmx256m" -f test.py
Change system property value
Using Jacl:wsadmin -javaoption "-Dcom.ibm.websphere.management.application.client.jspReloadEnabled=true"
wsadmin.sh -javaoption "-Dcom.ibm.websphere.management.application.client.jspReloadEnabled=true"
Using Jython:
wsadmin -lang jython -javaoption "-Dcom.ibm.websphere.management.application.client.jspReloadEnabled=true"
wsadmin.sh -lang jython -javaoption "-Dcom.ibm.websphere.management.application.client.jspReloadEnabled=true"
Enclose the Java system property with double-quotation marks ("").
Enclose multiple Java options with double-quotation marks (""); for example:
wsadmin -javaoption "-Dcom.ibm.websphere.management.application.client.jspReloadEnabled=true
-Dcom.ibm.websphere.management.application.enableDistribution=true"
JSR160RMI connection with security
Using Jacl:wsadmin -conntype JSR160RMI -port JSR160rmiportnumber -user userid
-password password
wsadmin.sh -conntype JSR160RMI -port JSR160rmiportnumber -user userid
-password password
Using Jython:
wsadmin -lang jython -conntype JSR160RMI -port JSR160portnumber -user userid
-password password
wsadmin.sh -lang jython -conntype JSR160 -port JSR160rmiportnumber -user userid
-password password
The element, rmiportnumber, for your connection is displayed in the administrative console as BOOTSTRAP_ADDRESS.
- Specify user and password information in the soap.client.props file for the SOAP connector, the sas.client.props file for the JSR160RMI connector or the Remote Method Invocation (RMI) connector, or the ipc.client.props file for the Inter-Process Communications (IPC) connector. The soap.client.props, sas.client.props, and ipc.client.props files are located in the properties directory of your application server profile.
- Wait for the wsadmin tool to prompt the user for login information instead of providing the login information within a properties file.
RMI connection with security
Using Jacl:wsadmin -conntype RMI -port rmiportnumber -user userid
-password password
wsadmin.sh -conntype RMI -port rmiportnumber -user userid
-password password
Using Jython:
wsadmin -lang jython -conntype RMI -port rmiportnumber -user userid
-password password
wsadmin.sh -lang jython -conntype RMI -port rmiportnumber -user userid
-password password
The element, rmiportnumber, for your connection is displayed in the administrative console as BOOTSTRAP_ADDRESS.
- Specify user and password information in the soap.client.props file for the SOAP connector, the sas.client.props file for the JSR160RMI connector or the Remote Method Invocation (RMI) connector, or the ipc.client.props file for the Inter-Process Communications (IPC) connector. The soap.client.props, sas.client.props, and ipc.client.props files are located in the properties directory of your application server profile.
- Wait for the wsadmin tool 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
Using Jacl:wsadmin -conntype NONE -c "$AdminApp uninstall app"
wsadmin.sh -conntype NONE -c "\$AdminApp uninstall app"
or
wsadmin.sh -conntype NONE -c '$AdminApp uninstall app'
Using Jython:
wsadmin -lang jython -conntype NONE -c "AdminApp.uninstall('app')"
wsadmin.sh -lang jython -conntype NONE -c "\AdminApp.uninstall('app')"
or
wsadmin.sh -lang jython -conntype NONE -c 'AdminApp.uninstall('app')'