WebLogic Scripting Tool

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Using the WebLogic Scripting Tool

The WebLogic Scripting Tool (WLST) is a command-line scripting environment that you can use to create, manage, and monitor WebLogic Server domains. It is based on the Java scripting interpreter, Jython. In addition to supporting standard Jython features such as local variables, conditional variables, and flow control statements, WLST provides a set of scripting functions (commands) that are specific to WebLogic Server. You can extend the WebLogic scripting language to suit your needs by following the Jython language syntax. See http://www.jython.org.

The following sections describe the WebLogic Scripting Tool:

 


Using WLST Online or Offline

You can use WLST as the command-line equivalent to the WebLogic Server Administration Console (WLST online) or as the command-line equivalent to the Configuration Wizard (WLST offline). For information about the WebLogic Server Administration Console, see Administration Console Online Help. For information about the Configuration Wizard, see Creating WebLogic Domains Using the Configuration Wizard.

Using WLST Online

You can use WLST to connect to a running Administration Server and manage the configuration of an active domain, view performance data about resources in the domain, or manage security data (such as adding or removing users). You can also use WLST to connect to Managed Servers, but you cannot modify configuration data from Managed Servers.

WLST online is a Java Management Extensions (JMX) client. It interacts with a server’s in-memory collection of Managed Beans (MBeans), which are Java objects that provide a management interface for an underlying resource. For information on WebLogic Server MBeans, see Understanding WebLogic Server MBeans in Developing Custom Management Utilities with JMX.

Using WLST Offline

Without connecting to a running WebLogic Server instance, you can use WLST to create domain templates, create a new domain based on existing templates, or 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. The schemas that define a domain’s configuration document are in the following locations:

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

 


Interactive Mode, Script Mode, and Embedded Mode

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

Interactive Mode

Interactive mode, in which you enter a command and view the response at a command-line prompt, 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.

Script Mode

Scripts invoke a sequence of WLST commands without requiring your input, much like a shell script. Scripts contain WLST commands in a text file with a .py file extension, for example, filename.py. You use script files with the Jython commands for running scripts.

Using WLST scripts, you can:

For information about sample scripts that WebLogic Server installs, see WLST Sample Scripts.

Embedded Mode

In embedded mode, you instantiate the WLST interpreter in your Java code and use it to run WLST commands and scripts. All WLST commands and variables that you use in interactive and script mode can be run in embedded mode.

Listing 2-1 illustrates how to instantiate the WLST interpreter and use it to connect to a running server, create two servers, and assign them to clusters.

Listing 2-1 Running WLST From a Java Class
package wlst;
import java.util.*;
import weblogic.management.scripting.utils.WLSTInterpreter;
import org.python.util.InteractiveInterpreter;
/**
 * Simple embedded WLST example that will connect WLST to a running server,
 * create two servers, and assign them to a newly created cluster and exit.
 * <p>Title: EmbeddedWLST.java</p>
 * <p>Copyright: Copyright (c) 2004</p>
 * <p>Company: BEA Systems</p>
 */
public class EmbeddedWLST 
{
  static InteractiveInterpreter interpreter = null;
  EmbeddedWLST() {
    interpreter = new WLSTInterpreter();
  }
private static void connect() {
    StringBuffer buffer = new StringBuffer();
    buffer.append("connect('weblogic','weblogic')");
    interpreter.exec(buffer.toString());
  }
private static void createServers() {
    StringBuffer buf = new StringBuffer();
    buf.append(startTransaction());
    buf.append("man1=create('msEmbedded1','Server')\n");
    buf.append("man2=create('msEmbedded2','Server')\n");
    buf.append("clus=create('clusterEmbedded','Cluster')\n");
    buf.append("man1.setListenPort(8001)\n");
    buf.append("man2.setListenPort(9001)\n");
    buf.append("man1.setCluster(clus)\n");
    buf.append("man2.setCluster(clus)\n");
    buf.append(endTransaction());
    buf.append("print ‘Script ran successfully ...’ \n");
    interpreter.exec(buf.toString());
  }
private static String startTransaction() {
    StringBuffer buf = new StringBuffer();
    buf.append("edit()\n");
    buf.append("startEdit()\n");
    return buf.toString();
  }
private static String endTransaction() {
    StringBuffer buf = new StringBuffer();
    buf.append("save()\n");
    buf.append("activate(block='true')\n");
    return buf.toString();
  }
  public static void main(String[] args) {
    new EmbeddedWLST();
    connect();
    createServers();
  }
}

 


Security for WLST

WLST uses the WebLogic Security Framework to prevent unauthorized users from modifying a domain or from viewing encrypted data. The following sections describe the actions you must take to satisfy WLST security requirements:

Securing the WLST Connection

If you use WLST to connect to a WebLogic Server instance, Oracle recommends that you connect to the server instance through the administration port. The administration port is a special, secure port that all WebLogic Server instances in a domain can use for administration traffic.

By default, this port is not enabled, but Oracle recommends that you enable the administration port in a production environment. Separating administration traffic from application traffic ensures that critical administration operations (starting and stopping servers, changing a server's configuration, and deploying applications) do not compete with high-volume application traffic on the same network connection.

The administration port requires all communication to be secured using SSL. By default, all servers in a domain use demonstration certificate files for SSL, but these certificates are not appropriate for a production environment.

For information about configuring the administration port, see “Administration Port and Administrative Channel” in Configuring Server Environments.

Securing Access to Configuration Data

A WebLogic Server domain stores its configuration data in a collection of XML documents that are saved in the domain directory. For example, these configuration documents describe the names, listen addresses, and deployed resources in the domain. 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).

You must use your own security measures to make sure that only authorized users can access your domain’s configuration files through the file system. Anyone who is authorized to access the domain’s configuration files through the file system can use a text editor, WLST offline, or other tools to edit the configuration files.

Securing Access from WLST Online

If you use WLST to connect to a running instance of WebLogic Server, you must provide the credentials (user name and password) of a user who has been defined in the active WebLogic security realm. Once you are connected, a collection of security policies determine which configuration attributes you are permitted to view or modify. (See Default Security Policies for MBeans in the WebLogic Server MBean Reference.)

When you invoke the WLST connect command, you can supply user credentials by doing any of the following:

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.

The 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, the ServerMBean exposes the password that is used to secure access through the IIOP protocol in an attribute named DefaultIIOPPasswordEncrypted.

Oracle recommends the following pattern for writing and reading encrypted attributes:

With WLST offline:

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 and read encrypted values with WLST online:

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. For more information, see Managing Security Data (WLST Online).

 


Main Steps for Using WLST in Interactive or Script Mode

The following sections summarize the steps for setting up and using WLST:

Setting Up Your Environment

To set up your environment for WLST:

  1. Install and configure the WebLogic Server software, as described in the Installation Guide
  2. Add WebLogic Server classes to the CLASSPATH environment variable and WL_HOME\server\bin to the PATH environment variable, where WL_HOME refers to the top-level installation directory for WebLogic Server.
  3. You can use a WL_HOME\server\bin\setWLSEnv script to set both variables.

    On Windows, a shortcut on the Start menu sets the environment variables and invokes WLST (ToolsArrow symbolWebLogic Scripting Tool).

Invoking WLST

Use the following syntax to invoke WLST (see Table 2-1 for a description of the command options):

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

Table 2-1 Command Options for WLST
Option
Description
-Dweblogic.security.SSL.
ignoreHostnameVerification=true
-Dweblogic.security.TrustKeyStore=
DemoTrust
Use these system properties if you plan to connect WLST to a WebLogic Server instance through an SSL listen port, and if the server instance is using the demonstration SSL keys and certificates.
-loadProperties propertyFilename
Use this option to load properties into the WLST session, where propertyFilename is the name of a file that contains name=value pairs.
You cannot use this option when you are importing WLST as a Jython module (see Importing WLST as a Jython Module).
Instead of using this command-line option, you can use the loadproperties WLST command. See loadProperties.
-skipWLSModuleScanning
Use this option to reduce startup time by skipping package scanning and caching for WLS modules.
[-i] filePath.py
Use this option to run a WLST script, where filePath.py is an absolute or relative pathname for the script.
By default, WLST exits (stops the Java process) after it executes the script. Include -i to prevent WLST from exiting.

Note: 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 c:\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
c:\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 ...
c:\>

Syntax for WLST Commands

Follow this syntax when entering WLST commands or writing them in a script:

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, enter the following command:

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, enter the following 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, run the following script:
WL_HOME\server\bin\setWLSEnv.cmd (or setWLSEnv.sh on UNIX)
where WL_HOME is the directory in which you installed WebLogic Server.

If you want 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" />

Parameters

Table 2-2 lists the wlst task parameters that you specify as attributes of the <wlst> element.

Table 2-2 wlst 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

The following sections describe the wlst task parameters that you specify as nested elements of the <wlst> element.

script

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

classpath

Specifies 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. See Path-like Structures in Apache Ant 1.7.1 Manual.

Examples

Example 1

In the following example, the createServer target does the following:

Example 2

In the following example, the loop target does the following:

Example 3

In the following example, the error 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:

  1. Invoke WLST.
  2. c:\>java weblogic.WLST
    wls:/(offline)>

  3. Use the writeIniFile command to convert WLST definitions and method declarations to a .py file.
  4. wls:/(offline)> writeIniFile("wl.py")
    The Ini file is successfully written to wl.py
    wls:/(offline)>

  5. Open a new command shell and invoke Jython directly by entering the following command:
  6. c:\>java org.python.util.jython

    The Jython package manager processes the JAR files in your classpath. The Jython prompt appears:

    >>>

  7. Import the WLST module into your Jython module using the Jython import command.
  8. >>>import wl

  9. Now you can use WLST methods in the module. For example, to connect WLST to a server instance:
  10. wl.connect('username','password')
    ....

    Note: 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, where WL_HOME refers to the top-level installation directory for WebLogic Server. All Python scripts that are defined within the WLST home directory are imported at WLST startup.

Note: 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.

Table 2-3 Customizing 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, as described in Importing WLST as a Jython Module.
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.


  Back to Top       Previous  Next