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:
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.
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.
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:
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
/server/lib/schema
, where WL_HOME is the directory in which you install WebLogic Server. Within this directory:domain.xsd
document is represented in the weblogic-domain-binding.jar
under the pathname META-INF/schemas/schema-1.xsd
. security.xsd
document is represented in the weblogic-domain-binding.jar
under the pathname META-INF/schemas/schema-0.xsd
.weblogic-diagnostics.xsd
document is represented in the diagnostics-binding.jar
under the pathname META-INF/schemas/schema-0.xsd
.Note the following restrictions for modifying configuration data with WLST offline:
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.
You can use any of the following techniques to invoke WLST commands:
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.
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.
For information about sample scripts that WebLogic Server installs, see WLST Sample Scripts.
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.
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();
}
}
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:
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.
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.
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:
For example:connect(‘weblogic’, ‘weblogic’, ‘localhost:7001’)
For more information, see connect.
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(‘weblogic’, ‘weblogic’, ‘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')
For more information, see connect and storeUserConfig.
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()
For more information, see connect.
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:
set
command. For example:set(‘DefaultIIOPPasswordEncrypted', ‘mypassword’)
WLST encrypts the string and writes the encrypted value to the domain’s configuration file.
For more information, see set.
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 ********
...
Whilewls:/offline/wl_server/Server/examplesServer>get('DefaultIIOPPasswordEncrypted')
returnsarray([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 and read encrypted values with WLST online:
set
command. For example:set(‘DefaultIIOPPassword', ‘mypassword’)
set(‘DefaultIIOPPasswordEncrypted', encrypt(‘mypassword’))
Caution: | 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.
get
command. For example:
get('DefaultIIOPPasswordEncrypted')
returnsarray([105, 114, 111, 110, 115, 116, 101, 101, 108], byte)
get
command. For example:get('DefaultIIOPPassword')
returnsmypassword
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).
The following sections summarize the steps for setting up and using WLST:
To set up your environment for WLST:
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.
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 (ToolsWebLogic Scripting Tool).
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 ]
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.
|
|||
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.
|
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')
To exit WLST, enter the exit()
command:
wls:/mydomain/serverConfig>exit()
Exiting WebLogic Scripting Tool ...
c:\>
Follow this syntax when entering WLST commands or writing them in a script:
'newServer'
or "newServer"
.\
) 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 pathname that contains a backslash:
readTemplate('c:\\userdomains\\mytemplates\\mytemplate.jar')
orreadTemplate(r'c:\userdomains\mytemplates\mytemplate.jar')
.
), 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:
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.
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.
Example:
wls:/mydomain/serverConfig> disconnect()
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" />
Table 2-2 lists the wlst
task parameters that you specify as attributes of the <wlst>
element.
The following sections describe the wlst
task parameters that you specify as nested elements of the <wlst>
element.
Contains a WLST script. This element is required if you do not use the fileName attribute to name a script file.
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.
In the following example, the createServer
target does the following:
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.)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.sys.argv
variable.wlst
Ant task fails to execute.<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>
In the following example, the loop
target does the following:
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.)t3://localhost:7001
and access and print the list of servers in the domain.wlst
task fails to execute, as per the failOnError="true
" setting.<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>
In the following example, the error
target:
thisWillCauseNameError
.false
" setting, even if the thisWillCauseNameError
variable does not exist and the wlst
Ant task fails to execute.<target name="error">
<wlst debug="true" failOnError="false">
<script>print thisWillCauseNameError</script>
</wlst>
</target>
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:
c:\>
java weblogic.WLST
wls:/(offline)>
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)>
c:\>
java org.python.util.jython
The Jython package manager processes the JAR files in your classpath. The Jython prompt appears:
import
command.
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. |
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.
This script can be imported into other Jython modules, as described in Importing WLST as a Jython Module.
|