WebLogic Scripting Tool

Configuring Existing Domains

The following sections describe using WLST to update an existing domain:

• Using WLST Online to Update an Existing Domain

• Using WLST Offline to Update an Existing Domain

• Managing Security Data (WLST Online)

• Deploying Applications

 

---

Using WLST Online to Update an Existing Domain

Because WLST online interacts with an active domain, all online changes to a domain are controlled by the change management process, which loosely resembles a database transaction. For more information on making and managing configuration changes, see Configuration Change Management Process in Understanding Domain Configuration.

Table 6-1 describes the steps for using WLST online to update an existing domain.

Table 6-1 Steps for Updating an Existing Domain (Offline)

To...	Use this command...	For more information, see...
Access the edit MBean hierarchy	edit() This command places WLST at the root of the edit MBean hierarchy, which is the editable DomainMBean.	edit
Obtain a lock on the current configuration To indicate that configuration changes are in process, an exclamation point (!) appears at the end of the WLST command prompt.	startEdit([waitTimeInMillis], [timeoutInMillis], [exclusive])	startEdit
Modify the domain	Browsing and online editing commands	Browse Commands Editing Commands
(Optional) Validate your edits	validate()	validate
Save your changes	save()	save
Distribute your changes to the working configuration MBeans on all servers in the domain	activate([timeout], [block])	activate
Release your lock on the configuration	stopEdit([defaultAnswer])	stopEdit
(Optional) Determine if a change you made to an MBean attribute requires you to re-start servers	isRestartRequired([attributeName])	isRestartRequired

The WLST online script in Listing 6-1 connects WLST to an Administration Server, initiates an edit session that creates a Managed Server, saves and activates the change, initiates another edit session, creates a startup class, and targets it to the newly created server.

Start WebLogic Server before running this script. See Invoking WLST. Listing 6-1 Creating a Managed Server

connect("username","password")

edit()

startEdit()

svr = cmo.createServer("managedServer")

svr.setListenPort(8001)

svr.setListenAddress("my-address")

save()

activate(block="true")

startEdit()

sc = cmo.createStartupClass("my-startupClass")

sc.setClassName("com.bea.foo.bar")

sc.setArguments("foo bar")

# get the server mbean to target it

tBean = getMBean("Servers/managedServer")

if tBean != None:

    print "Found our target"

    sc.addTarget(tBean)

save()

activate(block="true")

disconnect()

exit()

 

Tracking Configuration Changes

For all changes that are initiated by WLST, you can use the showChanges command which displays all the changes that you made to the current configuration from the start of the edit session, including any MBean operations that were implicitly performed by the server. See Listing 6-2.

Start WebLogic Server before running this script. See Invoking WLST. Listing 6-2 Displaying Changes

wls:/offline> connect('username','password')

wls:/mydomain/serverConfig> edit()

wls:/mydomain/edit> startEdit()

Starting an edit session ...

wls:/mydomain/edit !> cmo.createServer('managed2')

[MBeanServerInvocationHandler]mydomain:Name=managed2,Type=Server

wls:/mydomain/edit !> cd('Servers/managed2')

wls:/mydomain/edit/Servers/managed2 !> cmo.setListenPort(7702)

wls:/mydomain/edit/Servers/managed2 !> showChanges()

Changes that are in memory and saved to disc but not yet activated are:

MBean Changed           : mydomain:Name=mydomain,Type=Domain

Operation Invoked       : add

Attribute Modified      : Servers

Attributes Old Value    : null

Attributes New Value    : managed2

Server Restart Required : false

MBean Changed           : mydomain:Name=managed2,Type=Server

Operation Invoked       : modify

Attribute Modified      : StagingDirectoryName

Attributes Old Value    : null

Attributes New Value    : .\managed2\stage

Server Restart Required : true

MBean Changed           : mydomain:Name=managed2,Type=Server

Operation Invoked       : modify

Attribute Modified      : Name

Attributes Old Value    : null

Attributes New Value    : managed2

Server Restart Required : true

MBean Changed           : mydomain:Name=managed2,Type=Server

Operation Invoked       : modify

Attribute Modified      : ListenPort

Attributes Old Value    : null

Attributes New Value    : 7702

Server Restart Required : false

wls:/mydomain/edit/Servers/managed2 !> save()

wls:/mydomain/edit !> activate()

Started the activation of all your changes.

The edit lock associated with this edit session is released once the activation is successful.

The Activation task for your changes is assigned to the variable 'activationTask'

You can call the getUser() or getStatusByServer() methods on this variable to determine the status of your activation

[MBeanServerInvocationHandler]mydomain:Type=ActivationTask

wls:/mydomain/edit/Servers/managed2>

The getActivationTask function provides information about the activation request and returns the latest ActivationTaskMBean which reflects the state of changes that a user is currently making or made recently. You invoke the methods that this interface provides to get information about the latest activation task in progress or just completed. For detailed information, see ActivationTaskMBean in the WebLogic Server MBean Reference.

The WLST online script in Listing 6-3 connects WLST to a server instance as an administrator, gets the activation task, and prints the user and the status of the task. It also prints all the changes that took place.

Start WebLogic Server before running this script. See Invoking WLST. Listing 6-3 Checking the Activation Task

connect("theAdministrator","weblogic")

at = getActivationTask()

print "The user for this Task "+at.getUser()+" and the state is "+at.getState()

changes = at.getChanges()

for i in changes:

    i.toString()

 

Undoing or Canceling Changes

WLST offers two commands to undo or cancel changes:

• The undo command reverts all unsaved or unactivated edits.

  You specify whether to revert all unactivated edits (including those that have been saved to disk), or all edits made since the last save operation. See undo.

• The cancelEdit command releases the edit lock and discards all unsaved changes. See cancelEdit.

 

Additional Operations and Attributes for Change Management

The standard change-management commands described in the previous section are convenience commands for invoking operations in the ConfigurationManagerMBean. In addition to these operations, the ConfigurationManagerMBean contains attributes and operations that describe edit sessions. For detailed information, see ConfigurationManagerMBean in the WebLogic Server MBean Reference.

To access this MBean, use the WLST getConfigManager command. See getConfigManager.

The WLST online script in Listing 6-4 connects WLST to a server instance as an administrator, checks if the current editor making changes is a particular operator, then cancels the configuration edits. The script also purges all the completed activation tasks.

Start WebLogic Server before running this script. See Invoking WLST. Listing 6-4 Using the Configuration Manager

connect("theAdministrator","weblogic")

cmgr = getConfigManager()

user = cmgr.getCurrentEditor()

if user == "operatorSam":

    cmgr.undo()

    cmgr.cancelEdit()

cmgr.purgeCompletedActivationTasks()

 

---

Using WLST Offline to Update an Existing Domain

To update an existing domain using WLST offline, perform the steps described in Table 6-2.

Caution:

Oracle recommends that you do not use WLST offline to manage the configuration of an active domain. Offline edits are ignored by running servers and can be overwritten by JMX clients such as WLST online or the WebLogic Server Administration Console. Table 6-2 Steps for Updating an Existing Domain (Offline) To... Use this command... For more information, see... Open an existing domain for update readDomain(domainDirName) readDomain Extend the current domain (optional) addTemplate(templateFileName) addTemplate Modify the domain (optional) Browsing and editing commands Browsing Information About the Configuration Hierarchy (Offline) Editing a Domain (Offline). Save the domain updateDomain() updateDomain Close the domain closeDomain() closeDomain

 

---

Managing Security Data (WLST Online)

In the WebLogic Security Service, an Authentication provider is the software component that proves the identity of users or system processes. An Authentication provider also remembers, transports, and makes that identity information available to various components of a system when needed.

A security realm can use different types of Authentication providers to manage different sets of users and groups. (See Authentication Providers in Developing security providers for WebLogic Server.) You can use WLST to invoke operations on the following types of Authentication providers:

• The default WebLogic Server Authentication provider, AuthenticatorMBean. By default, all security realms use this Authentication provider to manage users and groups.

• Custom Authentication providers that extend weblogic.security.spi.AuthenticationProvider and extend the optional
  Authentication SSPI MBeans. See SSPI MBean Quick Reference in Developing security providers for WebLogic Server.

The following sections describe basic tasks for managing users and groups using WLST:

• Determining If You Need to Access the Edit Hierarchy

• Creating a User

• Adding a User to a Group

• Verifying Whether a User Is a Member of a Group

• Listing Groups to Which a User Belongs

• Listing Users and Groups in a Security Realm

• Changing a Password

• Protecting User Accounts in a Security Realm

For information about additional tasks that the AuthenticationProvider MBeans support, see AuthenticationProviderMBean in the WebLogic Server MBean Reference.

 

Determining If You Need to Access the Edit Hierarchy

If you are using WLST to change the configuration of a security MBean, access the edit hierarchy and start an edit session. For example, if you change the value of the LockoutThreshold attribute in UserLockoutManagerMBean, be in the edit hierarchy.

If you invoke security provider operations to add, modify, or remove data in a security provider data store, WLST does not allow you to be in the edit hierarchy. Instead, invoke these commands from the serverConfig or domainConfig hierarchy. For example, you cannot invoke the createUser operation in an AuthenticatorMBean MBean from the edit hierarchy. WLST enforces this restriction to prevent the possibility of incompatible changes. For example, an edit session could contain an unactivated change that removes a security feature and will invalidate modifications to the provider's data.

 

Creating a User

To create a user, invoke the UserEditorMBean.createUser method, which is extended by the security realm's AuthenticationProvider MBean. For more information, see the createUser method in the WebLogic Server MBean Reference.

The method requires three input parameters:

username password user-description

WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig or domainConfig hierarchy.

The following WLST online script invokes createUser on the default authentication provider. For information on how to run this script, see Invoking WLST. Listing 6-5 Creating a User

from weblogic.management.security.authentication import UserEditorMBean

print "Creating a user ..."

atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator")

atnr.createUser('my_user','my_password','new_admin')

print "Created user successfully"

 

Adding a User to a Group

To add a user to a group, invoke the GroupEditorMBean.addMemberToGroup method, which is extended by the security realm's AuthenticationProvider MBean. For more information, see the addMemberToGroup method in the WebLogic Server MBean Reference.

The method requires two input parameters:

groupname username

WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig or domainConfig hierarchy.

The following WLST online script invokes addMemberToGroup on the default Authentication Provider. For information on how to run this script, see Invoking WLST. Listing 6-6 Adding a User to a Group

from weblogic.management.security.authentication import GroupEditorMBean

print "Adding a user ..."

atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator")

atnr.addMemberToGroup('Administrators','my_user')

print "Done adding a user"

 

Verifying Whether a User Is a Member of a Group

To verify whether a user is a member of a group, invoke the GroupEditorMBean.isMember method, which is extended by the security realm's AuthenticationProvider MBean. For more information, see the isMember method in the WebLogic Server MBean Reference.

The method requires three input parameters:

groupname username boolean

where boolean specifies whether the command searches within child groups. If you specify true, the command returns true if the member belongs to the group that you specify or to any of the groups contained within that group.

WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig or domainConfig hierarchy.

The following WLST online script invokes isMember on the default Authentication Provider. For information on how to run this script, see Invoking WLST. Listing 6-7 Verifying Whether a User is a Member of a Group

from weblogic.management.security.authentication import GroupEditorMBean

print "Checking if isMember of a group ... "

atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator")

if atnr.isMember('Administrators','my_user',true) == 0:

  print "my_user is not member of Administrators"

else:

  print "my_user is a member of Administrators"

 

Listing Groups to Which a User Belongs

To see a list of groups that contain a user or a group, invoke the MemberGroupListerMBean.listMemberGroups method, which is extended by the security realm's AuthenticationProvider MBean. For more information, see the listMemberGroups method in the WebLogic Server MBean Reference.

The method requires one input parameter:

memberUserOrGroupName

where memberUserOrGroupName specifies the name of an existing user or a group.

WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig or domainConfig hierarchy.

The following WLST online script invokes listMemberGroups on the default Authentication provider. For information on how to run this script, see Invoking WLST. Listing 6-8 Listing Groups to Which a User Belongs

from weblogic.management.security.authentication import MemberGroupListerMBean

print "Listing the member groups ..."

atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator")

x = atnr.listMemberGroups('my_user')

print x

The method returns a cursor, which refers to a list of names. The NameLister.haveCurrent, getCurrentName, and advance operations iterate through the returned list and retrieve the name to which the current cursor position refers. See Name ofListerMBean in the WebLogic Server MBean Reference.

 

Listing Users and Groups in a Security Realm

To see a list of user or group names, you invoke a series of methods, all of which are available through the AuthenticationProvider interface:

• The GroupReaderMBean.listGroups and UserReaderMBean.listUsers methods take two input parameters: a pattern of user or group names to search for, and the maximum number of names that you want to retrieve.

  Because a security realm can contain thousands (or more) of user and group names that match the pattern, the methods return a cursor, which refers to a list of names.

  For more information, see the listGroups and listUsers operations in the WebLogic Server MBean Reference.

• The NameLister.haveCurrent, getCurrentName, and advance operations iterate through the returned list and retrieve the name to which the current cursor position refers. For more information, see Name ofListerMBean in the WebLogic Server MBean Reference.

• The NameLister.close operation releases any server-side resources that are held on behalf of the list.

WLST cannot invoke these commands from the edit hierarchy, but it can invoke them from the serverConfig or domainConfig hierarchy.

The WLST online script in Listing 6-9 lists all the users in a realm and the groups to which they belong. For information on how to run this script, see Invoking WLST. Listing 6-9 Listing Users and Groups

from weblogic.management.security.authentication import UserReaderMBean

from weblogic.management.security.authentication import GroupReaderMBean

realm=cmo.getSecurityConfiguration().getDefaultRealm()

atns = realm.getAuthenticationProviders()

for i in atns:

  if isinstance(i,UserReaderMBean):

    userReader = i

    cursor = i.listUsers("*",0)

    print 'Users in realm '+realm.getName()+' are: '

    while userReader.haveCurrent(cursor):

      print userReader.getCurrentName(cursor)

      userReader.advance(cursor)

    userReader.close(cursor)

for i in atns:

  if isinstance(i,GroupReaderMBean):

    groupReader = i

    cursor = i.listGroups("*",0)

    print 'Groups in realm are: '

    while groupReader.haveCurrent(cursor):

      print groupReader.getCurrentName(cursor)

      groupReader.advance(cursor)

    groupReader.close(cursor)

 

Changing a Password

To change a user's password, invoke the UserPasswordEditorMBean.changeUserPassword method, which is extended by the security realm's AuthenticationProvider MBean. For more information, see the changeUserPassword method in the WebLogic Server MBean Reference.

WLST cannot invoke this command from the edit hierarchy, but it can invoke the command from the serverConfig or domainConfig hierarchy.

The following WLST online script invokes changeUserPassword on the default Authentication Provider: For information on how to run this script, see Invoking WLST. Listing 6-10 Changing a Password

from weblogic.management.security.authentication import UserPasswordEditorMBean

print "Changing password ..."

atnr=cmo.getSecurityConfiguration().getDefaultRealm().lookupAuthenticationProvider("DefaultAuthenticator")

  atnr.changeUserPassword('my_user','my_password','new_password')

print "Changed password successfully"

 

Protecting User Accounts in a Security Realm

The UserLockoutManagerMBean provides a set of attributes to protect user accounts from intruders. By default, these attributes are set for maximum protection. You can decrease the level of protection for user accounts. For example, you can increase the number of login attempts before a user account is locked, increase the time period in which invalid login attempts are made before locking the user account, or change the amount of time a user account is locked. For more information, see the UserLockoutManagerMBean interface in the WebLogic Server MBean Reference.

The following tasks provide examples for invoking UserLockoutManagerMBean methods:

• Set Consecutive Invalid Login Attempts

• Unlock a User Account

Note that because these tasks edit MBean attributes, WLST must connect to the Administration Server, navigate to the edit hierarchy, and start an edit session.

Set Consecutive Invalid Login Attempts

The following WLST online script sets the number of consecutive invalid login attempts before a user account is locked out. For information on how to run this script, see Invoking WLST. Listing 6-11 Setting Consecutive Invalid Login Attempts

from weblogic.management.security.authentication import UserLockoutManagerMBean

edit()

startEdit()

#You have two choices for getting a user lockout manager to configure

# 1 - to configure the default realm's UserLockoutManager:

ulm=cmo.getSecurityConfiguration().getDefaultRealm().getUserLockoutManager()

# 2 - to configure another realm's UserLockoutManager:

#ulm=cmo.getSecurityConfiguration().lookupRealm("anotherRealm").getUserLockoutManager()

ulm.setLockoutThreshold(3)

save()

activate()

Unlock a User Account

The following WLST online script unlocks a user account. For information on how to run this script, see Invoking WLST. Listing 6-12 Unlocking a User Account

from weblogic.management.security.authentication import UserLockoutManagerMBean

serverRuntime()

ulm=cmo.getServerSecurityRuntime().getDefaultRealmRuntime().getUserLockoutManagerRuntime()

#note1 : You can only manage user lockouts for the default realm starting from when the server was booted (versus other non-active realms).

#note2 : If the default realm's user lockout manager's LockoutEnabled attribute is false, then the user lockout manager's runtime MBean will be null.

#That is, you can only manage user lockouts in the default realm if its user lockout manager is enabled.

if ulm != None:

  ulm.clearLockout("myuser")

 

---

Deploying Applications

The process for deploying applications varies depending on whether you use WLST offline or WLST online.

 

Using WLST Online to Deploy Applications

When WLST is connected to a domain's Administration Server, use the deploy command to deploy applications. (See deploy.)

The command in Listing 6-13 deploys a sample application from the WebLogic Server ExamplesServer domain. Listing 6-13 Deploying Applications

# Deploying Applications

deploy("mainWebApp","C:/bea/wlserver_10.3/samples/server/examples/build/mainWebApp")

Notes:

• You must invoke the deploy command on the computer that hosts the Administration Server.

• You do not need to be in an edit session to deploy applications.

For more information using WLST for deploying applications, see Deployment Tools in Deploying Applications to WebLogic Server.

 

Using WLST Offline to Deploy Applications

Table 6-3 describes the steps for using WLST offline to deploy applications in an existing domain.

Table 6-3 Steps for Deploying Applications (Offline)

To...	Use this command...	For more information, see...
Use the Template Builder to create an application template.		Creating Templates Using the Domain Template Builder
Open an existing domain or template	readDomain(domainDirName)	readDomain readTemplate
Add the application template to the domain.	addTemplate(templateFileName)	addTemplate
Save the domain	updateDomain()	updateDomain
Close the domain	closeDomain()	closeDomain

For an example of using the addTemplate command, see the following sample WLST script:

WL_HOME\common\templates\scripts\wlst\clusterMedRecDomain.py, where WL_HOME refers to the top-level installation directory for WebLogic Server