WebLogic Server

WLST provides an interactive mode in which you enter a command and view the response at a command-line prompt. Interactive mode is useful for learning the tool, prototyping command syntax, and verifying configuration options before building a script

When entering commands interactively, you want to minimize typing and quickly correct any mistakes. In this blog entry, I summarize the various command line editing options available in WLST in Windows and Unix environments.

Windows environment

When running on a Windows system, WLST uses the Windows command shell for the WLST console. The Windows shell provides a number of keys that can be used to edit and recall commands. There are the common keys:

• LEFT ARROW and RIGHT ARROW to move within a command

• HOME and END to move to the start and end of a command

• UP ARROW and DOWN ARROW to move within the command history
  

But there are also useful keys that are not as well known

• F7 shows a dialog box with the command history

• F8 walks backwards through the command history, but only displays commands that match the text to the left of the cursor

• CTRL LEFT ARROW and CTRL RIGHT ARROW to move to the next or previous word in a command
  

The following link provides a good description of all of the keys supported by the Windows shell

http://www.microsoft.com/technet/scriptcenter/topics/winpsh/manual/hotkeys.mspx

Unix environment

In a Unix environment, WLST does not provide any command line editing capabilities. However, you can use a 3rd party tool like JLine to provide line editing in WLST.

JLine provides the following editing capabilities:

• Command history
  
• Line editing
  
• Custom key bindings
  

For more information about JLine refer to http://jline.sourceforge.net/index.html

To use JLIne with WLST, follow these steps.

1. Download JLine from http://jline.sourceforge.net/downloads.html
   Unzip the file and put the jline jar (current version is jline-0.9.94.jar) into a directory on your machine.

2. Add the jline jar (current version is jline-0.9.94.jar) to the CLASSPATH

3. Run JLine as follows

   java jline.ConsoleRunner weblogic.WLST

4. Alternatively, you can copy the $WL_HOME/common/bin/wlst.sh and then add jline.ConsoleRunner before weblogic.WLST
   

The default keys in JLine are:

• UP ARROW and DOWN ARROW to move within the command history
  
• CTRL-N and CTRL-P to move within the command history

  
  
  

• LEFT ARROW and RIGHT ARROW to move within a command
  
• CTRL-B moves to the previous character
  
• CTRL-G moves to the previous word
  
• CTRL-A moves to the beginning of the line

  
  
  

• CTRL-F moves to the next character
  
• CTRL-E moves to the end of the line

  
  
  

• CTRL-U deletes all characters before the cursor
  
• CTRL-W deletes the word before the cursor
  

See the JLine documentation for information on customizing the key bindings using the keybindings.properties file.

Deployment command and tools deal with libraries in the same way as applications. The same set of commands are supported for libraries as for applications. There are, however, additional restrictions on library undeployment and redeployment. Undeployment or redeployment of a library is disallowed in case there are any deployed applications that refer to it in a running server. This does not necessarily interfere with upgrade scenarios. The recommended practice for upgrading shared libraries is to use versions and not to use "exact-match" while referring to libraries. A new version of library may be deployed without touching the older version. The applications that need to be upgraded may then simply be redeployed.

There is, however, a need for developers who create these libraries to test a change in deployed libraries in an iterative development scenario. If the developer does not mind loosing application state, she could use getReferencingRuntimes() methods of LibraryRuntimeMBean to identify referring applications and perform the following steps:

1. Undeploy referring applications
2. Redeploy library
3. Deploy applications from the list gathered in #1

Here is a simple function that implements steps 1 - 3:

def redeployLibraryWithApps(libraryName):
  serverRuntime()
  cd('LibraryRuntimes/'+libraryName)
  apps=cmo.getReferencingRuntimes()
  appPaths={}
  domainConfig()
  cd('AppDeployments')
  for app in apps:
    appId = app.getApplicationIdentifier()
    cd(appId)
    appPaths[appId] = cmo.getAbsoluteSourcePath()
    cd('..')
    undeploy(appId)
  redeploy(libraryName)
  for appId in appPaths.keys():
    deploy(appId, appPaths[appId])
  return

Such a function may then be used in WLST scripts:

if (len(sys.argv) < 4):

  print "Usage java weblogic.WLST redeployLib.py [username] [password] [library-name]"

  exit()

connect(sys.argv[1],sys.argv[2])

redeployLibraryWithApps(sys.argv[3])

disconnect()

(Picture licensed from quapan under Creative Commons)

More and more users are utilizing the nodemanager agent to start and monitor their WebLogic server instances. This helps ensure high availability of the WebLogic Server with automatic restarts as well as supporting automatic whole server migration. With this increased use there has also been an increase in scenarios for starting a WebLogic Server instance. In fact some questions have come up on how to configure the domain for setting specific properties or environment variables for a WebLogic Server instance when it is started through the nodemanager agent.

The best method for specifying command line properties for a server is by specifying those properties in the ServerStartMBean's arguments attribute. Each ServerMBean has a ServerStartMBean that stores start up specific values. These values can be set in the console by visiting the server specific configuration page, and then finding the "ServerStart" tab where the attributes can be set. These values can also be set in an edit session using WLST:
cd('Servers/YOUR_SERVER_NAME/ServerStart/YOUR_SERVER_NAME')
set('Arguments', '-Dweblogic.debug.DebugServerMigration')

Setting the values in the ServerStartMBean will ensure that "-Dweblogic.debug" flags or other custom properties are passed to the server. This is because a start call from the console or from WLST will go through the admin server, gathering the appropriate properties from the configuration, and send this information to the nodemanager. The information will be passed to the server regardless of whether the nodemanager is configured to start the server using a java command line (default) or a start script.

Storing the information in the ServerStartMBean also ensures that the information is centrally stored in the config.xml and will be referenced no matter which machine and nodemanager is used when starting the WebLogic Server. This will help to set the value once and maintain it in the configuration as opposed to storing it in start scripts scattered across multiple machines.

Another requirement may be an environment variable be specified prior to starting the server. There are 2 different ways to do this.

1. Make use of a custom start script that will contain the specific environment variables necessary. To do this, first configure the nodemanager to use a custom start script by specifying StartScriptEnabled=true and StartScriptName=customStartWebLogic.sh in the nodemanager.properties file or on the command line when starting the nodemanager. Then create the customStartWebLogic.sh in the domain directory that will set the appropriate variables and subsequently call startWebLogic.sh. An very basic example of customStartWebLogic.sh below:

export FOO=foo_value
. ./startWebLogic.sh

2. Make use of the environment that the java based nodemanager is running in to pass that information on to the server. To do this, set the necessary environment variables prior to starting the nodemanager.

Both of these solutions allow for multiple servers to be started through the nodemanager without having to set the same property for each server. But they also create an extra configuration step for each machine that will be used in the domain. The advantages of creating a custom start script is that the configuration will preserve the correct environment variable, where the nodemanager environment may leave room for a mistake where the environment variable is not correctly set.

WebLogic Server provides several administration tools such as the WLS Console (a graphical user interface) and WLST (a tool that runs Jython-based configuration scripts).

If you need to make small ad hoc changes or one time configuration changes, the WLS Console is a great choice. However, sometimes you need to repeatedly make a set of coordinated changes. For example, you might want to scale up a domain by periodially adding an SSL-enabled server to an existing cluster as the load goes up. In these cases, writing a WLST script can be a better choice. A script guarantees consistency and saves the administrator from having to repeatedly make coordinated changes across a number of console pages.

So, how do you get started writing your WLST script, especially if you're not a WLST script expert? The WLS Console provides a recording feature that writes out the edits you make in the console to a WLST script.
The basic idea is that you:

1. Log into the WLS Console and turn on script recording.


2. Use the WLS console to make some changes (e.g add a new SSL-enabled server to a existing cluster).


3. Turn off script recording.


4. Hand edit the captured script to clean it up and parameterize it (for example, have it prompt for the server name).

This can be a lot easier than starting from scratch since the console will show you which WLST commands you should be using.

This blog walks you through how to use the WLS Console's WLST script recording feature to create a script. The script prompts the adminstrator for a server name, listen address, listen port and SSL listen port. Then it creates a new SSL-enabled server with these values and adds it to the existing cluster named 'MyCluster'.

For this blog, I'm assuming that you're using a development mode domain that has the 'Automatically Acquire Lock and Activate Changes' console preference enabled (this is the default for development mode domains). I'm also assuming your domain already has a cluster named 'MyCluster'.

Here are the steps.

Step 1 - Turn On Recording
Log into the WLS Console and click 'Record' (in the the toolbar near the top of the page). This starts WLST script recording. When you start recording, the console prints out the name of the WLST script file it will create. For example:

The recording session has started. Recording to C:\mydomain\Script1251228165047.py.

Any configuration changes you make will be recorded in this script. Remember the name of this script since you'll be hand editing it later.

Note: deployment plan changes and security data changes (such as adding, deleting and modifying users, groups, roles and policies) will not be captured in the script.

Step 2 - Use the WLS Console to Make Typical Edits
Use the WLS Console to make some changes to the domain's configuration. For this example, create a new server in 'MyCluster', enable SSL for the server and customize the server's listen address, listen port and SSL listen port:

1. Click 'Servers' on the console home page.


2. Click 'New' to create a new server.


3. Set 'Server Name' to 'MyServer'.


4. Set 'Server Listen Address' to 'MyListenAddress'.


5. Set 'Listen Port' to '7777'.


6. Select the 'Yes, make this server a member of an existing cluster.' radio button.


7. Select 'MyCluster' from the list of clusters.


8. Click 'Finish'.


9. Click 'MyServer' in the servers table.


10. Click the 'SSL Listen Port Enabled' check box.


11. Set 'SSL Listen Port' to '8888'.


12. Click 'Save'.

Step 3 - Turn Off Recording
Click 'Record' again in the toobar near the top of the page. This stops WLST script recording. The console will print out the name of the script again:

The recording session has ended. Script recorded to C:\mydomain\Script1251228165047.py.

You now have a script that shows how to add a new SSL-enabled server named 'MyServer' to the cluster 'MyCluster':

startEdit()

cd('/')
cmo.createServer('MyServer')

cd('/Servers/MyServer')
cmo.setListenAddress('MyListenAddress')
cmo.setListenPort(7777)
cmo.setCluster(getMBean('/Clusters/MyCluster'))

activate()

startEdit()
cmo.setListenPortEnabled(true)
cmo.setJavaCompiler('javac')
cmo.setClientCertProxyEnabled(false)
cmo.setMachine(None)

cd('/Servers/MyServer/SSL/MyServer')
cmo.setEnabled(true)
cmo.setListenPort(8888)

activate()

startEdit()

If you look at this script, you'll notice that it isn't ready to use yet:

• It doesn't connect to the admin server at the beginning or disconnect at the end


• It doesn't call 'edit' to tell WLST to use the 'edit' MBean server. Note: the administration server has several different MBean servers. The 'edit' MBean server is the one that lets you view and manage the domain's configuration.


• There are extra 'activate' and 'startEdit' calls. This is because 'Automatically Acquire Lock and Activate Changes' is enabled (this preference makes every console page uses a separate configuration editing session).


• The server name, cluster name, listen address, listen port and SSL listen port values are hard coded.

Step 4 - Edit the Captured Script
Make a copy of the captured script, then edit the copy to address these issues.

• Call 'connect' at the beginning of the script. To connect, WLST needs to know the admin server url as well as the admin user name and password. You have two choices on how to get this information:
• Prompt for them or get them from the command line, then pass them to the 'connect' command.


• Don't pass any parameters to the 'connect' command. Instead, always run WLST from the domain directory on the admin server's machine. When you do this, WLST can automatically figure out the username, password, and url. This example takes this approach.
• Call 'edit' to tell WLST to use the admin server's 'edit' JMX server.


• Call 'disconnect' at the end of the script.


• Remove the extra 'activate' and 'startEdit' commands.


• Parameterize the script, that is, let the administrator specify the server name, listen address, listen port and SSL listen port. The two main ways to get these parameters are to prompt for them or to get them from the command line. This example prompts for them. Note: Since this example wants to show how to add new servers to an existing cluster, it leaves the cluster name hard coded in the script (ie. 'MyCluster'). This is typical. Most scripts want to parameterize some values and hard code others.


• You also might want to add some error handling to the script. This example does not show how to do this.

Here is the edited script (e.g. C:\temp\MyCreateServerScript.py):

connect()
edit()

myServerName = raw_input('Enter server name:')
myListenAddress = raw_input('Enter listen address:')
myListenPort = int(raw_input('Enter listen port:'))
mySSLListenPort = int(raw_input('Enter SSL listen port:'))

startEdit()

cd('/')
cmo.createServer(myServerName)

cd('/Servers/' + myServerName)
cmo.setListenAddress(myListenAddress)
cmo.setListenPort(myListenPort)
cmo.setCluster(getMBean('/Clusters/MyCluster'))

cmo.setListenPortEnabled(true)
cmo.setJavaCompiler('javac')
cmo.setClientCertProxyEnabled(false)
cmo.setMachine(None)

cd('/Servers/' + myServerName + '/SSL/' + myServerName)
cmo.setEnabled(true)
cmo.setListenPort(mySSLListenPort)

activate()
disconnect()

You now have a parameterized WLST script that your administrator can use to add new SSL-enabled servers to 'MyCluster' as the load goes up.

Using the Script
Here's how to run the script:

1. 'cd' to your domain's directory on the admin server's machine


2. run the .\bin\setDomainEnv.cmd script


3. java weblogic.WLST C:\temp\MyCreateServerScript.py
• Enter server name:server99


• Enter listen address:listenaddress99


• Enter listen port:7099


• Enter SSL listen port:8099

At this point, you can log into your domain's WLS Console, go to the 'Servers' table and view the new server that the script created.

Summary
In summary, if you want to create a parameterized WLST script that edits a domain's configuration:

1. Log in into your domain's WLS Console and turn on recording.


2. Use the console to make the kind of configuration changes that you want your script to have.


3. Turn off recording.


4. Make a copy of the captured script, clean it up and parameterize it.

For more information on the WebLogic Server Console's WLST script recording feature, see http://download-llnw.oracle.com/docs/cd/E15051_01/wls/docs103/ConsoleHelp/taskhelp/console/RecordWLSTScripts.html
For more information on the WebLogic Server WLST scripting tool, see http://download.oracle.com/docs/cd/E13222_01/wls/docs91/config_scripting/index.html