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.
Important: 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,
you might see a permission denied error in the log files. To avoid
this issue, consider one of the following policies:
Use specific profiles 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.
The options for the wsadmin tool are case insensitive.
If you specify an empty string in place of a command options, the
wsadmin tool displays general help information.
Avoid trouble: - 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 white 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 some white space to the command
string. This white space might cause the command or script to failure.
If you need to include white space in a command either use the list
syntax instead of the string syntax, or enclose the string containing
the white space within [ ] (brackets).
gotcha
Use the following command-line invocation syntax
for the wsadmin scripting client:
wsadmin [-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
To
shorten the length of the command, you can type the command in the
following way:
wsadmin -javaoption "java_option java_option"
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.
trns
- -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 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 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 the
com.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 as
noecho.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:
com.ibm.ws.scripting.noechoParamNo=3,5
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:
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
dbpassword and userpassword 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.
- -?
- 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.
Note: 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:
/home/MyDir/Myjar.jar;/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
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
Using
Jython:
wsadmin -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:
![[IBM i]](../images/iseries.gif)
Specify multiple Java options
together or separately:
wsadmin -javaoption "-Xms128m -Xmx256m" -f test.jacl
or
wsadmin -javaoption -Xms128m -javaoption -Xmx256m -f test.jacl
Using
Jython:
![[IBM i]](../images/iseries.gif)
Specify multiple Java options
together or separately:
wsadmin -lang jython -javaoption "-Xms128m -Xmx256m" -f test.py
or
wsadmin -lang jython -javaoption -Xms128m -javaoption -Xmx256m -f test.py
- Change system property value
- Using Jacl:
wsadmin -javaoption "-Dcom.ibm.websphere.management.application.client.jspReloadEnabled=true"
Using
Jython:
wsadmin -lang jython -javaoption "-Dcom.ibm.websphere.management.application.client.jspReloadEnabled=true"
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
Using Jython:
wsadmin -lang jython -conntype JSR160RMI -port JSR160portnumber -user userid
-password password
The element, rmiportnumber,
for your connection is displayed in the administrative console as
BOOTSTRAP_ADDRESS.
Attention: 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, 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.
- RMI connection with security
- Using Jacl:
wsadmin -conntype RMI -port rmiportnumber -user userid -password password
Using
Jython:
wsadmin -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.
Attention: 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,
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.
- Local mode of operation to perform a single command
- Using Jacl:
wsadmin -conntype NONE -c "$AdminApp uninstall app"
Using
Jython:
wsadmin -lang jython -conntype NONE -c "AdminApp.uninstall('app')"