Using the WebLogic Scripting Tool

Using the WebLogic Scripting Tool

+
Search Tips | Advanced Search

Overview
Security for WLST
Connect
Set Up Your Environment
Invoke WLST
Exit WLST
Syntax for WLST Commands
Redirect Error and Debug Output to a File
Get Help
Run WLST from Ant
Import WLST as a Jython Module
Customize WLST

Overview

You can use WLST to connect to a running Administration Server to..

manage the configuration of an active domain
view performance data about resources in the domain
manage security data (such as adding or removing users

You can use WLST to connect to Managed Servers, but you cannot modify configuration data from Managed Servers.
WLST online is a JMX client, interacting with a server's in-memory collection of Managed Beans (MBeans).
Without connecting to a running WebLogic Server instance, you can use WLST to...

create domain templates
create a new domain based on existing templates
extend an existing, inactive domain

You cannot use WLST offline to view performance data about resources in a domain or modify security data (such as adding or removing users).
WLST offline provides read and write access to the configuration data that is persisted in the domain's config directory or in a domain template JAR created using Template Builder.
Scripts contain WLST commands (Jython) in a text file with a .py file extension.
There are sample scripts.
In embedded mode, you instantiate the WLST interpreter in your Java code and use it to run WLST commands and scripts.

WLST Security

Oracle recommends using the administration port.
By default, this port is not enabled.
Separating admin traffic from app traffic ensures that critical administration operations do not compete with high-volume application traffic on the same network connection.
Demonstration certificate files are configured.
Domain store config data in a collection of XML documents. When one or more servers in a domain are running, each server instance maintains an in-memory representation of the configuration data as a collection of Managed Beans (MBeans).
Anyone who is authorized to access the domain's configuration files through the file system can edit the configuration files.

Connecting

To connect using commandline credentials...
connect('weblogic', 'weblogic', 'localhost:7001')

To create a user config file that contains credentials in an encrypted form and a key file that WebLogic Server uses to unencrypt the credentials...
connect('weblogic', 'weblogic', 'localhost:7001') storeUserConfig('/myFiles/myuserconfigfile.secure', '/myFiles/myuserkeyfile.secure')

To connect using the user configuration file and key file:
connect(userConfigFile='/myfiles/myuserconfigfile.secure', userKeyFile='/myfiles/myuserkeyfile.secure')

You can connect using a boot.properties file, which contains encrypted credentials , which is created by default when you create an Administration Server. To use, start WLST from the domain directory.
/mydomain/> java weblogic.WLST
wls:/offline> connect()

Security policies determine access.

Writing and Reading Encrypted Configuration Values

Some attributes of a WebLogic Server domain's configuration are encrypted to prevent unauthorized access to sensitive data. For example, the password that a JDBC data source uses to connect to an RDBMS is encrypted. Attribute values are saved in the domain's configuration document as an encrypted string. In a running server instance, the values are available as an MBean attribute in the form of an encrypted byte array. The names of encrypted attributes end with Encrypted.
For example...
DefaultIIOPPasswordEncrypted

To write an encrypted value with WLST offline, pass the name of the encrypted attribute and an unencrypted string to the set command...
set('DefaultIIOPPasswordEncrypted', 'mypassword')

WLST encrypts the string and writes the encrypted value to the domain's configuration file.
WLST offline does not display the unencrypted value of an encrypted attribute. If you use the ls command to display management attributes, WLST offline returns asterisks as the value of encrypted attributes. If you use the get command, WLST offline returns a byte array that represents asterisks.
For example:
wls:/offline/wl_server/Server/examplesServer>ls()
returns
...
-rw- DefaultIIOPPasswordEncrypted ********
...

While
wls:/offline/wl_server/Server/examplesServer>get('DefaultIIOPPasswordEncrypted')
returns
array([42, 42, 42, 42, 42, 42, 42, 42], byte)

With WLST online, for each encrypted attribute, an MBean also contains an unencrypted version. For example, ServerMBean contains an attribute named DefaultIIOPPasswordEncrypted which contains the encrypted value and an attribute named DefaultIIOPPassword, which contains the unencrypted version of the value.
To write an encrypted value, start an edit session. Then do either of the following:

Pass the name of the unencrypted attribute and an unencrypted string to the set command...
set('DefaultIIOPPassword';, 'mypassword')

Pass the name of the encrypted attribute and an encrypted byte array to the set command. You can use the encrypt command to create the encrypted byte array
set('DefaultIIOPPasswordEncrypted', encrypt('mypassword'))

Do not pass an unencrypted string to the encrypted attribute. The encrypted attribute assumes that the value you pass to it is already encrypted.
When you activate the edit, WebLogic Server writes the encrypted value to the domain's configuration file.

To read the encrypted value of the attribute, pass the name of the encrypted attribute to the get command...
get('DefaultIIOPPasswordEncrypted')

...returns...
array([105, 114, 111, 110, 115, 116, 101, 101, 108], byte)
To read the unencrypted value of the attribute, pass the name of the unencrypted attribute to the get command...
get('DefaultIIOPPassword')
returns
mypassword

Securing Access to Security Data

The user names and passwords of WebLogic Server users, security groups, and security roles are not stored in a domain's XML configuration documents. Instead, a domain uses a separate software component called an Authentication provider to store, transport, and provide access to security data. Authentication providers can use different types of systems to store security data. The Authentication provider that WebLogic Server installs uses an embedded LDAP server.
When you use WLST offline to create a domain template, WLST packages the Authentication provider's data store along with the rest of the domain documents. If you create a domain from the domain template, the new domain has an exact copy of the Authentication provider's data store from the domain template.
You cannot use WLST offline to modify the data in an Authentication provider's data store.
You can, however, use WLST online to interact with an Authentication provider and add, remove, or modify users, groups, and roles.

Set Up Your Environment

To set up your environment for WLST:

Install and configure the WebLogic Server software.
Add WebLogic Server classes to the CLASSPATH environment variable. Add...
WL_HOME/server/bin

...to the PATH environment variable.
WL_HOME/server/bin/setWLSEnv

Invoke WLST
java [ -Dweblogic.security.SSL.ignoreHostnameVerification=true \
       -Dweblogic.security.TrustKeyStore=DemoTrust ] \
        weblogic.WLST  \
     [ -loadProperties propertyFilename ] \
     [ -skipWLSModuleScanning ] \
     [ [-i] filePath.py ] 
Where...

-Dweblogic.security.SSL.ignoreHostnameVerification=true
-Dweblogic.security.TrustKeyStore=DemoTrust
Connect WLST to a WebLogic Server instance through an SSL listen port.
-loadProperties propertyFilename
Load properties into the WLST session.
You cannot use this option when you are importing WLST as a Jython module. Use loadproperties instead.
-skipWLSModuleScanning
Deduce startup time by skipping package scanning and caching for WLS modules.
[-i] filePath.py
Run a WLST script.

By default, WLST exits (stops the Java process) after it executes the script. Include -i to prevent WLST from exiting.
If a WLST script named wlstProfile.py exists in the directory from which you invoke WLST or in user.home (the home directory of the operating system user account as determined by the JVM), WLST automatically runs the wlstProfile.py script; you do not need to specify the name of this WLST script file on the command-line.
Instead of using this command-line option, you can use the following command after you start WLST:
execfile('filePath.py').

Examples

To use WLST in script mode:
java weblogic.WLST /myscripts/myscript.py

To run a WLST script on a WebLogic Server instance that uses the SSL listen port and the demonstration certificates:
java -Dweblogic.security.SSL.ignoreHostnameVerification=true
-Dweblogic.security.TrustKeyStore=DemoTrust weblogic.WLST
/myscripts/myscript.py

To use WLST in interactive mode:
java weblogic.WLST

To connect to a WebLogic Server instance after you start WLST in interactive mode:
wls:/offline> connect('weblogic','weblogic','localhost:7001')

Exiting WLST

To exit WLST, enter the exit() command:
wls:/mydomain/serverConfig> exit()
Exiting WebLogic Scripting Tool ...
/>
Syntax for WLST Commands

Command names and arguments are case sensitive.
Enclose arguments in single or double quotes. For example, 'newServer' or "newServer".
Precede backslashes with another backslash or precede the entire string with a lower-case r character.
readTemplate('c:\\userdomains\\mytemplates\\mytemplate.jar') or
readTemplate(r'c:\userdomains\mytemplates\mytemplate.jar')

When using WLST offline, the following characters are not valid in names of management objects:

period (.)
forward slash (/)
backward slash (\)

If you need to cd to a management object whose name includes a forward slash (/), surround the object name in parentheses...
cd('JMSQueue/(jms/REGISTRATION_MDB_QUEUE)')

Redirecting Error and Debug Output to a File

To redirect WLST information, error, and debug messages from standard out to a file, enter:
redirect(outputFile,[toStdOut])
stopRedirect()

This command also redirects the output of the dumpStack() and dumpVariables() commands.
For example, to redirect WLST output to the logs/wlst.log file under the directory from which you started WLST...
wls:/mydomain/serverConfig> redirect('./logs/wlst.log')

For more information, see redirect and stopRedirect.

Getting Help

To display information about WLST commands and variables, enter the help command.
If you specify the help command without arguments, WLST summarizes the command categories. To display information about a particular command, variable, or command category, specify its name as an argument to the help command. To list a summary of all online or offline commands from the command line using the following commands, respectively:
   help('online')

   help('offline')
The help command will support a query; for example, help('get*') displays the syntax and usage information for all commands that begin with get.
For example, to display information about the disconnect command...
wls:/mydomain/serverConfig> help('disconnect')
The command returns the following:
Description:
Disconnect from a weblogic server instance.
Syntax:
disconnect()
Example:
wls:/mydomain/serverConfig> disconnect()

Running WLST from Ant

WebLogic Server provides a custom Ant task, wlst, that invokes a WLST script from an Ant build file. You can create a WLST script (.py) file and then use this task to invoke the script file, or you can create a WLST script in a nested element within this task.
For more information about Ant, see Apache Ant 1.7.1 Manual.
The wlst task is predefined in the version of Ant that is installed with WebLogic Server. To add this version of Ant to your build environment...
/WL_HOME/server/bin/setWLSEnv.sh

To use the wlst task with your own Ant installation, include the following task definition in your build file:
<taskdef name="wlst" classname="weblogic.ant.taskdefs.management.WLSTTask" />

wlst task parameters

Attribute Description Required
properties="propsFile" Name and location of a properties file that contains name-value pairs that you can reference in your WLST script. No
fileName="fileName" Name and location of the WLST script file that you would like to execute. If the specified WLST script file does not exist, this task fails. Yes, if no nested <script> is used.
arguments="arglist" List of arguments to pass to the script. These arguments are accessible using the sys.argv variable. No
failOnError="value" Boolean value specifying whether the Ant build will fail if this task fails. No; default is true.
executeScriptBeforeFile="value" Boolean value specifying whether this task invokes the script in the nested <script> element before the script file specified by the fileName attribute. This attribute defaults to true, specifying that the embedded script is invoked first. No; default is true.
debug="value" Boolean value specifying whether debug statements should be output when this task is executed. No; default is false.

Parameters Specified as Nested Elements

script

Contains a WLST script. This element is required if you do not use the fileName attribute to name a script file.

classpath

Classes to add to the classpath. Use this element if your script requires classes that are not already on the classpath.
This element is the standard Ant classpath element. You can specify a reference to a path element that you have defined elsewhere in the build file or nest elements that specify the files and directories to add to the class path.

Examples

Example 1

In the following example, the createServer target does the following:
Adds classes to the task's classpath.
Executes the script in the nested script element. This script connects to a domain's Administration Server at t3://localhost:7001.
Note that executeScriptBeforeFile is set to true, so this is invoked before the specified WLST script file.
Executes the script file myscript.py that is specified by the fileName attribute. The script file is located in the directory from which you started Ant. You could use such a file to start an edit session, create a new server, save, and activate the configuration changes.
Defines three arguments that are passed to the script. These arguments are accessible using the sys.argv variable.
Continues execution, as per the failOnError="false" setting, even if the wlst Ant task fails to execute.
Disables debugging.
<target name="configServer"> 

   <wlst debug="false" failOnError="false" executeScriptBeforeFile="true"  

    fileName="./myscript.py"> 

       <classpath>

         <pathelement location="${my.classpath.dir}"/>

       </classpath>

       <script>

         connect('weblogic','weblogic','t3://localhost:7001') 

     </script> 

   </wlst> 

</target> 
Example 2

In the following example, the loop target does the following:
Adds classes to the task's classpath using a path reference.
Executes the WLST script file myscript.py in the directory from which you started Ant.
Note that executeScriptBeforeFile is set to false, so the WLST script file is executed first, before the embedded script.
Executes the embedded script to connect to the server at t3://localhost:7001 and access and print the list of servers in the domain.
Results in a build failure if the wlst task fails to execute, as per the failOnError="true" setting.
Enables debugging.
<path id="my.classpath">


    <pathelement location="${my.classpath.dir}"/>


</path>


<target name="loop"> 


  <wlst debug="true" executeScriptBeforeFile="false" 

    fileName="./myscript.py" failOnError="true"> 

    <classpath>

        <pathelement location="${my.classpath.dir}"/>

    </classpath>

    <script>

       print 'In the target loop' 

       connect('weblogic','weblogic','t3://localhost:7001') 

       svrs = cmo.getServers() 

       print 'Servers in the domain are' 

       for x in svrs: print x.getName()

    </script>

  </wlst> 

</target> 
Example 3

In the following example, the error target:
Executes the embedded script to print the variable, thisWillCauseNameError.
Continues execution, as per the failOnError="false" setting, even if the thisWillCauseNameError variable does not exist and the wlst Ant task fails to execute.
Enables debugging.
<target name="error"> 

   <wlst debug="true" failOnError="false"> 

      <script>print thisWillCauseNameError</script> 

   </wlst> 

</target>
Importing WLST as a Jython Module

Advanced users can import WLST from WebLogic Server as a Jython module. After importing WLST, you can use it with your other Jython modules and invoke Jython commands directly using Jython syntax.
The main steps include converting WLST definitions and method declarations to a .py file, importing the WLST file into your Jython modules, and referencing WLST from the imported file.
To import WLST as a Jython module:

Invoke WLST.

>java weblogic.WLST
wls:/(offline)>

Use the writeIniFile command to convert WLST definitions and method declarations to a .py file.

wls:/(offline)> writeIniFile("wl.py")
The Ini file is successfully written to wl.py
wls:/(offline)>

Open a new command shell and invoke Jython directly...

>java org.python.util.jython

The Jython package manager processes the JAR files in your classpath. The Jython prompt appears:
>>>
Import the WLST module into your Jython module using the Jython import command.

>>>import wl

Now you can use WLST methods in the module. For example, to connect WLST to a server instance:

wl.connect('username','password')
....

When using WLST as a Jython module, in all WLST commands that have a block argument, block is always set to true, specifying that WLST will block user interaction until the command completes. See WLST Command and Variable Reference.

Customizing WLST

You can customize WLST using the WLST home directory, which is located at WL_HOME/common/wlst, by default. All Python scripts that are defined within the WLST home directory are imported at WLST startup.

You can customize the default WLST home directory by passing the following argument on the command line:
-Dweblogic.wlstHome=<another-directory>
The following table describes ways to customize WLST.

To define custom... Do the following... For a sample script, see...
WLST commands Create a Python script defining the new commands and copy that file to WL_HOME/common/wlst. WL_HOME/common/wlst/sample.py
Within this script, the wlstHomeSample() command is defined, which prints a String, as follows:
wls:/(offline)> wlstHomeSample()
Sample wlst home command
WLST commands within a library Create a Python script defining the new commands and copy that file to WL_HOME/common/wlst/lib.
The scripts located within this directory are imported as Jython libraries.
WL_HOME/common/wlst/lib/wlstLibSample.py
Within this script, the wlstExampleCmd() command is defined, which prints a String, as follows:
wls:/(offline)> wlstLibSample.wlstExampleCmd()
Example command
WLST commands as a Jython module Create a Python script defining the new commands and copy that file to...
WL_HOME/common/wlst/modules

This script can be imported into other Jython modules
WL_HOME/common/wlst/modules/wlstModule.py
A JAR file, jython-modules.jar, containing all of the Jython modules that are available in Jython 2.1 is also available within this directory.

Domain Config Schemas

The schemas that define a domain's configuration document are in...

http://www.bea.com/ns/weblogic/920/domain.xsd
http://www.bea.com/ns/weblogic/90/security.xsd
http://www.bea.com/ns/weblogic/weblogic-diagnostics/1.1/weblogic-diagnostics.xsd
In JAR files under...
WL_HOME/server/lib/schema

Within this directory:

domain.xsd is represented in the weblogic-domain-binding.jar under...
META-INF/schemas/schema-1.xsd

security.xsd is represented in the weblogic-domain-binding.jar under...
META-INF/schemas/schema-0.xsd

weblogic-diagnostics.xsd is represented in the diagnostics-binding.jar under...
META-INF/schemas/schema-0.xsd

Note the following restrictions for modifying configuration data with WLST offline:

Oracle recommends that you do not use WLST offline to manage the configuration of an active domain. Offline edits are ignored by running servers and can be overwritten by JMX clients such as WLST online or the WebLogic Server Administration Console.
As a performance optimization, WebLogic Server does not store most of its default values in the domain's configuration files. In some cases, this optimization prevents management objects from being displayed by WLST offline (because WebLogic Server has never written the corresponding XML elements to the domain's configuration files). For example, if you never modify the default logging severity level for a domain while the domain is active, WLST offline will not display the domain's Log management object.
If you want to change the default value of attributes whose management object is not displayed by WLST offline, first use the create command to create the management object. Then you can cd to the management object and change the attribute value.

Interactive Mode, Script Mode, and Embedded Mode

You can use any of the following techniques to invoke WLST commands:

Interactive Mode
Script Mode
Embedded Mode

Interactive Mode

Interactive mode is useful for learning the tool, prototyping command syntax, and verifying configuration options before building a script. Using WLST interactively is particularly useful for getting immediate feedback after making a critical configuration change. The WLST scripting shell maintains a persistent connection with an instance of WebLogic Server.
WLST can write all of the commands that you enter during a WLST session to a file. You can edit this file and run it as a WLST script. For more information, see startRecording and stopRecording.

Attribute	Description	Required
properties="propsFile"	Name and location of a properties file that contains name-value pairs that you can reference in your WLST script.	No
fileName="fileName"	Name and location of the WLST script file that you would like to execute. If the specified WLST script file does not exist, this task fails.	Yes, if no nested <script> is used.
arguments="arglist"	List of arguments to pass to the script. These arguments are accessible using the sys.argv variable.	No
failOnError="value"	Boolean value specifying whether the Ant build will fail if this task fails.	No; default is true.
executeScriptBeforeFile="value"	Boolean value specifying whether this task invokes the script in the nested <script> element before the script file specified by the fileName attribute. This attribute defaults to true, specifying that the embedded script is invoked first.	No; default is true.
debug="value"	Boolean value specifying whether debug statements should be output when this task is executed.	No; default is false.