2 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 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).

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).

The following sections describe how to use WLST online or offline:

Using WLST Online

You can use WLST to connect to a running Administration Server and manage the configuration of an active WebLogic 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 Using JMX for Oracle WebLogic Server.

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 WebLogic 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. See Browsing Information About the Configuration Hierarchy (Offline).

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 WebLogic 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 WebLogic 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 WebLogic 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, you must first use the create command to create the management object. Then you can cd to the management object and change the attribute value. See create in WLST Command Reference for WebLogic Server.

Interactive Mode, Script Mode, and Embedded Mode

WLST can be invoked in a variety of ways.

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. See startRecording and stopRecording in WLST Command Reference for WebLogic Server.

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:

  • Automate WebLogic Server configuration and application deployment

  • Apply the same configuration settings, iteratively, across multiple nodes of a topology

  • Take advantage of scripting language features, such as loops, flow control constructs, conditional statements, and variable evaluations that are limited in interactive mode

  • Schedule scripts to run at various times

  • Automate repetitive tasks and complex procedures

  • Configure an application in a hands-free data center

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. Prior to running the program with embedded WLST, you must invoke the following command to set the appropriate environment variables:

  • Windows: WL_HOME\server\bin\setWLSEnv.cmd

  • UNIX: WL_HOME/server/bin/setWLSEnv.sh

    On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.

Example 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.

Example 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: Oracle</p>
 */

public class EmbeddedWLST 
{
  static InteractiveInterpreter interpreter = null;
  EmbeddedWLST() {
    interpreter = new WLSTInterpreter();
  }

private static void connect() {
    StringBuffer buffer = new StringBuffer();
    buffer.append("connect('adminusername','adminpassword')"); 
    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 WebLogic 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 WebLogic 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. The default value for the administration port is 9002. 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 WebLogic 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 Administering Server Environments for Oracle WebLogic Server.

Securing Access to Configuration Data

A WebLogic 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 WebLogic 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 MBean Reference for Oracle WebLogic Server.)

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

  • Enter the credentials on the command line. This option is recommended only if you are using WLST in interactive mode.

    For example:

    connect('adminusername', 'adminpassword', 'localhost:7001'
    

    See connect in WLST Command Reference for WebLogic Server.

  • Enter the credentials on the command line, and then use the storeUserConfig command to create a user configuration file that contains your credentials in an encrypted form and a key file that WebLogic Server uses to unencrypt the credentials. On subsequent WLST sessions (or in WLST scripts), supply the name of the file instead of entering the credentials on the command line. This option is recommended if you use WLST in script mode because it prevents you from storing unencrypted user credentials in your scripts.

    For example, to create the user configuration file and key file:

    connect('adminusername', 'adminpassword', 'localhost:7001')
    storeUserConfig('c:/myFiles/myuserconfigfile.secure',
    'c:/myFiles/myuserkeyfile.secure') 
    

    To use the user configuration file and key file:

    connect(userConfigFile='c:/myfiles/myuserconfigfile.secure',
    userKeyFile='c:/myfiles/myuserkeyfile.secure')
    

    See connect and storeUserConfig in WLST Command Reference for WebLogic Server.

  • Invoke the connect command from a directory that contains the domain's boot.properties file. By default, when you create an Administration Server, WebLogic Server encrypts the credentials and stores them in a boot.properties file. WLST can use this file only if you start WLST from the domain directory.

    For example, if you have not deleted the domain's boot.properties file, you can start WLST and invoke the connect command as follows:

    c:\mydomain\> java weblogic.WLST
    wls:/offline> connect() 
    

    See connect in WLST Command Reference for WebLogic Server.

Writing and Reading Encrypted Configuration Values

Some attributes of a WebLogic 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:

  • To write an encrypted value, pass the name of the encrypted attribute and an unencrypted string to the set command. For example:

    set('DefaultIIOPPasswordEncrypted', '<password>')

    WLST encrypts the string and writes the encrypted value to the domain's configuration file.

    See set in WLST Command Reference for WebLogic Server.

  • 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) 
    

    See ls and get in WLST Command Reference for WebLogic Server.

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:

  • 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. For example:

      set('DefaultIIOPPassword', '<password>')

    • 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 (see encrypt in WLST Command Reference for WebLogic Server). For example:

      set('DefaultIIOPPasswordEncrypted', encrypt('<password>'))

    • Note:

      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. For example:

    get('DefaultIIOPPasswordEncrypted')
    

    returns

    array([105, 114, 111, 110, 115, 116, 101, 101, 108], byte) 
    

Securing Access to Security Data

The user names and passwords of WebLogic Server users, security groups, and security roles are not stored in a WebLogic domain's XML configuration files. Instead, a WebLogic 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. See Managing Security Data (WLST Online).

Main Steps for Using WLST in Interactive or Script Mode

When you use WLST interactive or script mode, you should understand how to invoke it, exit it, and its syntax.

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

Invoking WLST

You can invoke WLST in the following ways:

Note:

If you notice that it takes a long time to create or update a domain using WLST on a UNIX or Linux operating system, set the CONFIG_JVM_ARGS environment variable to the following value to resolve this issue:

-Djava.security.egd=file:/dev/urandom

See also Running WLST from Ant.

Invoking WLST Using Provided Shell Scripts

To invoke WLST using a shell script, execute the command that is appropriate for your environment. This is the recommended way to invoke WLST. Environment variables are automatically set when you invoke WLST this way. You can then enter WLST commands from within the WLST shell.

Note:

The following commands apply only to standalone WebLogic Server installations (those that do not include other Fusion Middleware components). Many Fusion Middleware components supply custom WLST commands. To use them, you must invoke WLST from the appropriate directory. See Using Custom WLST Commands in Administering Oracle Fusion Middleware.

UNIX

cd ORACLE_HOME/oracle_common/common/bin
./wlst.sh

ORACLE_HOME is the Oracle Home directory you specified at installation.

To set WLST properties in a UNIX environment prior to running WLST:

export WLST_PROPERTIES="-Dweblogic.security.SSL.ignoreHostnameVerification=true, 
-Dweblogic.security.TrustKeyStore=DemoTrust"
./wlst.sh 

Note:

To avoid log file name collisions when multiple WLST offline processes are running, set the following property in the environment prior to invoking WLST:

export WLST_PROPERTIES="-Dwlst.offline.log=./logs/debug.log"

Windows

cd ORACLE_HOME\oracle_common\common\bin
wlst.cmd

ORACLE_HOME is the Oracle Home directory you specified at installation.

Invoking WLST Using the java Command

To invoke WLST using the java command, you must first set up your environment for WLST. To set up your environment for WLST:

  1. Install and configure the WebLogic Server software, as described in Installing the Oracle WebLogic Server and Coherence Software in Installing and Configuring Oracle WebLogic Server and Coherence.
  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 full path to the WebLogic Server home directory.

    You can use the setWLSEnv script to set the required variables:

    • Windows: WL_HOME\server\bin\setWLSEnv.cmd

    • UNIX: WL_HOME/server/bin/setWLSEnv.sh

      On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.

After setting up your environment, use the following syntax to invoke WLST.

java 
   [ -Dweblogic.security.SSL.ignoreHostnameVerification=true
   -Dweblogic.security.TrustKeyStore=DemoTrust ]
   [ -Dweblogic.security.JavaStandardTrustKeyStorePassPhrase=password]
    [ -Dweblogic.security.CustomTrustKeyStoreFileName=filename
     -Dweblogic.security.TrustKeystoreType=jks
    [ -Dweblogic.security.CustomTrustKeyStorePassPhrase=password]]
    [ -Dweblogic.security.SSL.hostnameVerifier=classname]
   weblogic.WLST 
   [ -loadProperties propertyFilename ]
   [ -skipWLSModuleScanning ]
   [ [-i] filePath.py ] 

See Table 2-1 for a description of the WLST command options. See Table 2-2 for a description of the SSL arguments. Table 2-3 lists additional optional startup arguments for WLST.

Table 2-1 Command Options for WLST

Option Description

-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 in WLST Command Reference for WebLogic Server.

-skipWLSModuleScanning

Use this option to reduce startup time by skipping package scanning and caching for WebLogic Server 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').

Table 2-2 SSL Arguments

Argument Definition

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

ignoreHostNameVerification disables host name verification.

TrustKeyStore causes WLST to trust the CA certificates in the demonstration trust keystore (WL_HOME\server\lib\DemoTrust.jks).

TrustKeyStore is required if the server instance to which you want to connect is using the demonstration identity and certificates.

By default, WLST trusts only the CA certificates in the Java Standard Trust keystore (SDK_HOME\jre\lib\security\cacerts).

-Dweblogic.security. JavaStandardTrustKeyStorePassPhrase =password

Password that was used to secure the Java Standard Trust keystore.

If the Java Standard Trust keystore is protected by a password, and if you want to trust its CA certificates, you must use this argument.

By default, the Java Standard Trust keystore is not protected by a password.

-Dweblogic.security. CustomTrustKeyStoreFileName= filename-Dweblogic.security. TrustKeystoreType=jks

Causes WLST to trust the CA certificates in a custom keystore that is located at filename. You must use both arguments to trust custom keystores. The filename must match exactly the ServerMBean.CustomTrustKeyStoreFileName value persisted in config.xml; if the value specified in the CustomTrustKeyStoreFileName attribute is a relative pathname, you must also specify the same relative pathname in this argument.

-Dweblogic.security. CustomTrustKeyStorePassPhrase=password

Password that was used to secure the custom keystore.

You must use this argument only if the custom keystore is protected by a password.

-Dweblogic.security.SSL. hostnameVerifier=classname

Name of a custom Host Name Verifier class. The class must implement the weblogic.security.SSL.HostnameVerifier interface.

Table 2-3 Additional WLST Startup Arguments

Argument Description

-Dwlst.debug.init=value

If true, debug mode is turned on. If false, debug mode is turned off. The default is false.

-Dweblogic.wlstHome=path1: path2: ...: pathn

-Dweblogic.wlstHome=path1; path2; ...; pathn

A comma-separated list of directory paths from which to load .py files at startup. Note that the path separator is ':' on UNIX operating systems and ';' on Windows.

-Dwlst.offline.log=path

Sets the path and file name for WLST offline logging, for example, -Dwlst.offline.log=./logs/debug.log.

-Dwlst.offline.log.priority=debug

Sets the log priority level to debug for WLST offline logging.

Example 2-2 Examples of Invoking WLST Using the Java Command

To use WLST in script mode:

java weblogic.WLST c:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributeQueues.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:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributeQueues.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('adminusername','adminpassword','localhost:7001') 
Running Scripts

You can run WLST scripts in the following ways:

  • Include the script in the wlst.cmd or wlst.sh command:

    wlst.sh  /oracle/middleware/wlserver/common/templates/scripts/wlst/distributedQueues.py
    
  • Include the script in the java weblogic.WLST command. You can either include the full path to the script, as shown here:

    java weblogic.WLST c:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributedQueues.py
    

    or you can navigate to the directory where the script is located before invoking WLST, in which case you only need to include the script name in the command:

    cd C:/Oracle/Middleware/wlserver/common/templates/scripts/wlst
    java weblogic.WLST distributeQueues.py
    
  • After invoking interactive WLST, use the execfile() command:

    wls:offline> execfile('c:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributedQueues.py')

    Note:

    If you use backslashes (\) in the path name, be aware that WLST interprets them as a special character, which you must escape. See Syntax for WLST Commands.

Invoking WLST From the Start Menu

On Windows, a shortcut on the Start menu sets the environment variables and invokes WLST (Oracle WebLogic > WebLogic Server > Tools > WebLogic Scripting Tool).

Exiting WLST

To exit WLST, enter the exit() command:

wls:/mydomain/serverConfig> exit() 
Exiting WebLogic Scripting Tool ... 

Syntax for WLST Commands

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

  • Command names and arguments are case sensitive.

  • Enclose arguments in single or double quotes. For example, 'newServer' or "newServer".

  • If you specify a backslash character (\) in a string, either precede the backslash with another backslash or precede the entire string with a lower-case r character. The \ or r prevents Jython from interpreting the backslash as a special character.

    For example when specifying a file path name that contains a backslash:

    readTemplate('c:\\userdomains\\mytemplates\\mytemplate.jar', 'Expanded') 
    

    or

    readTemplate(r'c:\userdomains\mytemplates\mytemplate.jar', 'Expanded') 
    

    Note:

    When specifying path names in WLST commands on a Windows machine, you can use a forward slash (/). For example:

    readTemplate('c:/userdomains/templates/template.jar', 'Expanded')
    

    is as valid as

    readTemplate('c:\\userdomains\\templates\\template.jar', 'Expanded')
  • When using WLST offline, the following characters are not valid in names of management objects: period (.), forward slash (/), or backward slash (\).

    If you need to cd to a management object whose name includes a forward slash (/), surround the object name in parentheses. For example:

    cd('JMSQueue/(jms/REGISTRATION_MDB_QUEUE)')

Considerations When Invoking Multiple WLST Instances

At WLST startup, Jython stores information in a temporary directory based on the username of the person who started WLST. If the same user invokes two different WLST instances which will run at the same time, conflicts may occur when saving this information in the temporary directory.

If you plan to invoke multiple WLST instances with the same username, Oracle recommends that you define the java.io.tmpdir system property to point to a temporary directory that will not be shared by other WLST instances that are running at the same time. For example, include the following parameter in the Java command you use to start WLST:

-Djava.io.tmpdir=C:\mytempdir

Redirecting Error and Debug Output to a File

You can redirect error and debug information to a file.

To redirect WLST information, error, and debug messages from standard output 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') 

See redirect and stopRedirect in WLST Command Reference for WebLogic Server.

Getting Help for WLST

WLST provides command line help for each command.

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 supports 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, which 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 the Apache Ant 1.7.1 Manual at http://ant.apache.org/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, where WL_HOME is the directory in which you installed WebLogic Server.

WL_HOME\server\bin\setWLSEnv.cmd (or setWLSEnv.sh on UNIX)

On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.

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" /> 

WLST Task Parameters

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

Table 2-4 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.

replaceProperties="value"

Boolean value that specifies whether ant property expansion will work in the specified WLST script.

No; default is true.

WLST Task Parameters Specified as Nested Elements

Table 2-5 describes the wlst task parameters that you specify as nested elements of the <wlst> element.

Table 2-5 Parameters Specified as Nested Elements

Attribute Description Required

script

The script to be executed.

Required, if you do not use the fileName attribute to name a script file.

classpath

The classes to add to 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 at http://ant.apache.org/manual/using.html#path

No. Use if your script requires classes that are not already on the classpath.

WLST Ant Task Examples

The following sections show examples for the createServer, loop, and error targets.

CreateServer Target Example

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 WebLogic 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('adminusername','adminpassword','t3://localhost:7001') 
         </script> 
       </wlst> 
    </target> 
Loop Target Example

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 WebLogic 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 replaceProperties="true">
           print 'In the target loop' 
           connect('${admin.user}','${admin.password}','t3://localhost:7001') 
           svrs = cmo.getServers() 
           print 'Servers in the domain are' 
           for x in svrs: print x.getName()
        </script>
      </wlst> 
    </target> 
Error Target Example

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:

  1. Invoke WLST.
    cd ORACLE_HOME/oracle_common/common/bin
    ./wlst.sh
    wls:/offline> 
    
  2. 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> 
    
  3. Open a new command shell and invoke Jython directly by entering the following command:
    c:\>java org.python.util.jython 
    

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

    >>>
    
  4. Import the WLST module into your Jython module using the Jython import command.
    >>>import wl 
    
  5. Now you can use WLST methods in the module. For example, to connect WLST to a server instance:
    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 in WLST Command Reference for WebLogic Server.

    When running recorded scripts directly in a Jython interpreter, Boolean values of true and false can cause an error. Before running recorded scripts in a Jython interpreter, make one of the following changes to the script:

    • Add the following two lines to the script to define the true and false values:

    • true=1
      false=0
      
    • Change true and false values to wl.true or wl.false, where wl is the name from the import.

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>

Table 2-6 describes ways to customize WLST.

Table 2-6 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.

Sample Scripts For Defining new WLST Commands

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.

Sample Scripts For Defining new WLST Commands

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, which contains all of the Jython modules that are available in Jython 2.2.1, is also available within this directory.

To import wlstModule, see Import wlstModule for Modularity.

Integrated help for custom WLST commands

Define the help text for each command group and command in a resource bundle.

Use addHelpCommandGroup to add a command group to the list of command groups that are displayed by the help() command.

Use addHelpCommand to add a command to the list of commands that is displayed by the help('commandGroup') command.

Typically, you will call the addHelpCommandGroup and addHelpCommand from the .py file that contains the definition of your custom commands.

See Adding Integrated Help for Custom Commands.

Not applicable.

Adding Integrated Help for Custom Commands

You can customize WLST to include integrated help for any custom WLST commands you've defined. To add integrated help, you define the help text for each command group and command in a resource bundle, which can be either a class or a property resource file. You can define the help for multiple command groups in the same resource bundle.

Note:

The resource bundle must be present in the classpath.

The resource bundle contains the following entries for each command group:

<commandGroup>_ShortDescription=\
     <short description of command group>
<commandGroup>_Description=\
     \n<description of command group>

For example, the following lines define the short description and description for the command group navigate:

navigate_ShortDescription=\
     Lists commands for navigating the hierarchy of beans.
navigate_Description=\
     \n Navigates the hierarchy of beans and controls the prompt display. \n

When you enter the help() command to display a list of command groups, the short description for navigate is displayed in the listing:

wls:/offline>help()
WLST is a command line scripting tool to configure and administer a WebLogic Server. Try:
     help('all')        List all WLST commands available.
     help('browser')    List commands for browsing the hierarchy.
     help('navigate')   List commands for navigating the bean hierarchy.

When you enter the help('navigate') command, the description is displayed above the list of commands in the group:

wls:/offline> help('navigate')
Navigates the hierarchy of beans and controls the prompt display.
     help('mycd')     Navigate the hierarchy of beans.
     help('myprmpt')  Toggle the display of path information at the prompt.

The resource bundle contains help text entries for commands using a standard pattern. For each command name, there are several entries:

<commandName>_ShortDescription
<commandName>_Description
<commandName>_Example
<commandName>_Syntax

The following defines the help for mycd command:

mycd_ShortDescription=\
     Navigate the hierarchy of beans.

mycd_Description=\
     \nNavigate the hierarchy of configuration or runtime beans. This \
     \ncommand uses a model that is similar to navigating a file system \
     \nin a Windows or UNIX command shell. For example, to navigate back \
     \nto a parent configuration or runtime bean, enter mycd(".."). The \
     \ncharacter string .. (dot-dot) refers to the directory immediately \
     \nabove the current directory. To get back to the root configuration \
     \nbean after navigating to a configuration or runtime bean that is \
     \ndeep in the hierarchy, enter mycd("/"). \

mycd_Example=\
     wls:/mydomain/serverConfig> mycd('Servers')\n\
     wls:/mydomain/serverConfig/Servers> mycd('myserver)\n\
     wls:/mydomain/serverConfig/Servers/myserver>mycd('../..')\n\
     wls:/mydomain/serverConfig>

mycd_syntax=\
     mycd(mbeanName)
     \n- mbeanName = Path to the configuration or runtime bean in the namespace.\
     \n

The short description is shown to the right of the command name when you enter the help('commandGroup') command to list all commands in a group:

wls:/offline> help('navigate')
Navigates the hierarchy of beans and controls the prompt display.
   help('mycd')     Navigate the hierarchy of beans.
   help('myprmpt')  Toggle the display of path information at the prompt.     

The description, example, and syntax are displayed when you enter the help('commandName') command:

wls:/offline> help('mycd')

Description:

Navigate the hierarchy of configuration or runtime beans. This
command uses a model that is similar to navigating a file system
in a Windows or UNIX command shell. For example, to navigate back
to a parent configuration or runtime bean, enter mycd(".."). The
character string .. (dot-dot) refers to the directory immediately
above the current directory. To get back to the root configuration
bean after navigating to a configuration or runtime bean that is
deep in the hierarchy, enter mycd("/").

Syntax:
mycd(mbeanName)
- mbeanName = Path to the configuration or runtime bean in the namespace.

Example:

wls:/mydomain/serverConfig> mycd('Servers')\n\
wls:/mydomain/serverConfig/Servers> mycd('myserver)\n\
wls:/mydomain/serverConfig/Servers/myserver>mycd('../..')\n\
wls:/mydomain/serverConfig>

After defining the help text in the resource bundle, use addHelpCommandGroup to add the command group name to the list of command groups output by the help() command. Use addHelpCommand to add each command in a group to the list of commands displayed by the help('commandGroup') command. See addHelpCommandGroup and addHelpCommand in the WLST Command Reference for WebLogic Server.

For more information on resource bundles and localization, refer to http://download.oracle.com/javase/6/docs/api/java/util/ResourceBundle.html.

Sample Scripts For Defining new WLST Commands

The following sample script demonstrates how to define a new WLST command.

def wlstHomeSample():
     print 'Sample wlst home command'

Within this script, the wlstHomeSample() command is defined, which prints a text string:

wls:/offline> wlstHomeSample()
Sample wlst home command

When defining new WLST commands in this way, store the .py file in the WL_HOME/common/wlst directory.

The following sample script demonstrate usage of the WLST lib directory, where layered products and ISVs can add commands to WLST in their namespace. The script has the same structure as the previous example. It differs only in that it is stored in the WL_HOME/common/wlst/lib directory instead of the WL_HOME/common/wlst directory.

def wlstExampleCmd():
     print 'Example command'

Within this script, the wlstExampleCmd() command is defined, which prints a text string:

wls:/offline> wlstLibSample.wlstExampleCmd()
Example command

Note that you must create the WLST lib directory if it does not already exist.