Weblogic Interview Questions

How do I provide user credentials for starting a server?

When you create a domain, the Configuration Wizard prompts you to provide the username
and password for an initial administrative user. If you create the domain in development
mode, the wizard saves the username and encrypted password in a boot identity file. A
WebLogic Server instance can refer to a boot identity file during its startup process. If a
server instance does not find such a file, it prompts you to enter credentials.

If you create a domain in production mode, or if you want to change user credentials in an
existing boot identity file, you can create a new boot identity file.

Can I start a Managed Server if the Administration Server is unavailable?

By default, if a Managed Server is unable to connect to the specified Administration Server
during startup, it can retrieve its configuration by reading a configuration file and other files
directly. You cannot change the server's configuration until the Administration Server is
available. A Managed Server that starts in this way is running in Managed Server
Independence mode.

What is the function of T3 in WebLogic Server?

T3 provides a framework for WebLogic Server messages that support for enhancements.
These enhancements include abbreviations and features, such as object replacement, that
work in the context of WebLogic Server clusters and HTTP and other product tunneling. T3
predates Java Object Serialization and RMI, while closely tracking and leveraging these
specifications. T3 is a superset of Java Object. Serialization or RMI; anything you can do in
Java Object Serialization and RMI can be done over T3. T3 is mandated between WebLogic
Servers and between programmatic clients and a WebLogic Server cluster. HTTP and IIOP are
optional protocols that can be used to communicate between other processes and WebLogic
Server. It depends on what you want to do. For example, when you want to communicate
between a browser and WebLogic Server-use HTTP, or an ORB and WebLogic Server-IIOP.

How do you set the classpath?

WebLogic Server installs the following script that you can use to set the classpath that a
server requires:
WL_HOME\server\bin\setWLSEnv.cmd (on Windows)
WL_HOME/server/bin/setWLSEnv.sh (on UNIX)

Where WL_HOME is the directory in which you installed WebLogic Server.

How do stubs work in a WebLogic Server cluster?

Clients that connect to a WebLogic Server cluster and look up a clustered object obtain a
replica-aware stub for the object. This stub contains the list of available server instances that
host implementations of the object. The stub also contains the load balancing logic for
distributing the load among its host servers.

What happens when a failure occurs and the stub cannot connect to a WebLogic
Server instance?
When the failure occurs, the stub removes the failed server instance from its list. If there are
no servers left in its list, the stubb uses DNS again to find a running server and obtain a
current list of running instances. Also, the stub periodically refreshes its list of available
server instances in the cluster; this allows the stub to take advantage of new servers as they
are added to the cluster.

How does a server know when another server is unavailable?

WebLogic Server uses two mechanisms to determine if a given server instance is unavailable.

Each WebLogic Server instance in a cluster uses multicast to broadcast regular "heartbeat"
messages that advertise its availability. By monitoring heartbeat messages, server instances
in a cluster determine when a server instance has failed. The other server instances will drop
a server instance from the cluster, if they do not receive three consecutive heartbeats from
that server instance

WebLogic Server also monitors socket errors to determine the availability of a server
instance. For example, if server instance A has an open socket to server instance B, and the
socket unexpectedly closes, server A assumes that server B is offline.

How are notifications made when a server is added to a cluster?

The WebLogic Server cluster broadcasts the availability of a new server instance each time a
new instance joins the cluster. Cluster-aware stubs also periodically update their list of
available server instances.

How do clients handle DNS requests to failed servers?

If a server fails and DNS continues to send requests to the unavailable machine, this can
waste bandwidth. For a Java client application, this problem occurs only during startup.
WebLogic Server caches the DNS entries and removes the unavailable ones, to prevent the
client from accessing a failed server twice.

Failed servers can be more of a problem for browser-based clients, because they always use
DNS. To avoid unnecessary DNS requests with browser-based clients, use a third-party load-
balancer such as Resonate, BigIP, Alteon, and LocalDirector. These products mask multiple
DNS addresses as a single address. They also provide more sophisticated load-balancing
options than round-robin, and they keep track of failed servers to avoid routing unnecessary
requests.

How many WebLogic Servers can I have on a multi-cpu machine?

There are many possible configurations and each has its own advantages and disadvantages.
BEA WebLogic Server has no built-in limit for the number of server instances that can reside
in a cluster. Large, multi-processor servers such as Sun Microsystems, Inc. Sun Enterprise
10000, therefore, can host very large clusters or multiple clusters.

In most cases, WebLogic Server clusters scale best when deployed with one WebLogic Server
instance for every two CPUs. However, as with all capacity planning, you should test the
actual deployment with your target web applications to determine the optimal number and
distribution of server instances.

How can I set deployment order for applications?

WebLogic Server allows you to select the load order for applications. WebLogic Server
deploys server-level resources (first JDBC and then JMS) before deploying applications.
Applications are deployed in this order: connectors, then EJBs, then Web Applications. If the
application is an EAR, the individual components are loaded in the order in which they are
declared in the application.xml deployment descriptor.

Can I refresh static components of a deployed application without having to

redeploy the entire application?
Yes. You can use weblogic.Deployer to specify a component and target a server, using the
following syntax:

java weblogic.Deployer -adminurl http://admin:7001 -name appname -targets

server1,server2 -deploy jsps/*.jsp

When should I use the -nostage option?

Set the staging mode to -nostage (using weblogic.Deployer or the Administration Console) if
you don't want to copy deployment files but want to deploy an application from its present
location. All target servers must be able to access the same set of deployment files.

When should I use the external_stage option?

Set -external_stage using weblogic.Deployer if you want to stage the application yourself,
and prefer to copy it to its target by your own means.

Can I set the deployment order for application modules? For standalone modules?
The Load Order attribute controls the deployment order of standalone modules and
applications relative to other modules and applications of the same type. For example,
standalone EJBs with smaller Load Order values are deployed before those with higher
values.

Modules that are deployed as part of an Enterprise Application (EAR file or directory) are
deployed in the order in which they are specified in the application.xml deployment
descriptor.

What is the difference between the WL_HOME/config/examples/applications folder

and the WL_HOME/config/examples/stage folder?
The applications folder is intended for applications that are not yet ready for a production
environment. WebLogic Server dynamically deploys the contents of the applications folder.
The stage folder (or a folder that you create for the same purpose) is for storing copies of
deployment files that are ready for deployment in a production environment (deployments
that use the stage or external_stage deployment modes).

How do I turn the auto-deployment feature off?

The auto-deployment feature checks the applications folder every three seconds to determine
whether there are any new applications or any changes to existing applications and then
dynamically deploys these changes.

The auto-deployment feature is enabled for servers that run in development mode. To
disable auto-deployment feature, use one of the following methods to place servers in
production mode:

 In the Administration Console, click the name of the domain in the left pane, then
select the Production Mode checkbox in the right pane.
 At the command line, include the following argument when starting the domain's
Administration Server:

-Dweblogic.ProductionModeEnabled=true

Production mode is set for all WebLogic Server instances in a given domain.

Must EJBs be homogeneously deployed across a cluster? Why?

Yes. In WebLogic Server 6.0 and later, EJBs must be homogeneously deployed across a
cluster for the following reasons:

 To keep clustering EJBs simple

 To improve performance by avoiding cross-server calls. If EJBs are not deployed on all
servers, cross-server calls are more likely.
 To ensure that every EJB is available locall.y

 To ensure that all classes are loaded in an undeployable way. Every server must have
access to each EJB's classes so that it can be bound into the local JNDI tree. If only a
subset of the servers deploys the bean, the other servers will have to load the bean's
classes in their respective system classpaths which makes it impossible to undeploy
the beans.

Q. How do I provide user credentials for starting a server?

A. When you create a domain, the Configuration Wizard prompts you to provide the
username and password for an initial administrative user. If you create the domain in
development mode, the wizard saves the username and encrypted password in a boot
identity file. A WebLogic Server instance can refer to a boot identity file during its
startup process. If a server instance does not find such a file, it prompts you to enter
credentials.

If you create a domain in production mode, or if you want to change user credentials in
an existing boot identity file, you can create a new boot identity file. WebLogic Server
does not support copying a boot identity file from one server root directory to another.
For information on creating and using boot identity files, see Boot Identity Files in
Administration Console Online Help.

Q. Can I start a Managed Server if the Administration Server is unavailable?

A. By default, if a Managed Server is unable to connect to the specified Administration

Server during startup, it can retrieve its configuration by reading a configuration file and
other files directly. You cannot change the server's configuration until the Administration
Server is available. A Managed Server that starts in this way is running in Managed
Server Independence mode. For more information, see Starting a Managed Server When
the Administration Server Is Not Accessible in Configuring and Managing WebLogic
Server.

Q. What is the easiest way to set the classpath?

WebLogic Server installs the following script that you can use to set the classpath that a
server requires:
WL_HOME\server\bin\setWLSEnv.cmd (on Windows)
WL_HOME/server/bin/setWLSEnv.sh (on UNIX)

where WL_HOME is the directory in which you installed WebLogic Server. For more
information, see "Setting the Classpath" in the WebLogic Server Command Reference.

Q. How do I edit the config.xml file?

A. The persistent configuration for a domain of WebLogic Servers and clusters is stored
in an XML configuration file (config.xml). You can modify this file in the following
ways:

 Use the Administration Console. See "Using the Administration Console" in the
Administration Console Online Help.
 If you want to create scripts that automate domain management, use the
weblogic.Admin utility. See "weblogic.Admin Command-Line Reference" in the
.
 If you want to create Java-based management applications, use the Java
Management Extensions (JMX) Application Programming Interface (API). See
the Programming WebLogic Management Services with JMX guide.
 If you want to edit the config.xml file directly (not recommended), see the BEA
WebLogic Server Configuration Reference.

Q. Is there a quick way to create and start a remote Managed Server?

A. The recommended approach is to use the Domain Configuration Wizard, as described

in "Setting Up and Starting Managed Servers on a Remote Machine" in Creating
WebLogic Configurations Using the Configuration Wizard at http://e-
docs.bea.com/platform/docs81/confgwiz/multi.html.

For a streamlined approach, follow the instructions at "Starting Managed Servers From a
WebLogic Server Script" in the Administration Console Online Help.

Q. The Tree View pane of the WebLogic Console is not visible in my browser. How do I
enable it?

A. Enable the Sun Java Plug-In from the control panel.

WebLogic Server 9 Mock Exam

Question 1 – Objective 1 - Design Patterns

Which of these is not a valid design pattern type?
A. Fundamental
B. Presentation
C. Behavioral
D. Accidental

Question 2 – Objective 1 - Design Patterns

Design patterns describe:
A. The problem facing the Web Designer
B. How the pattern solves the problem
C. The consequences from using the pattern
D. None of the above

Question 3 – Objective 2 - J2EE Standard & General J2EE Concepts

How can software or hardware standards help distributed systems?
A. Provide separation of difficult problems to separate platforms
B. Allow modularization of complex hardware and software
C. Allow a larger portion of the project cost to go toward solving business software needs
D. All of the above

Question 4 – Objective 2 - J2EE Standard & General J2EE Concepts

Which of these standards are part of the J2EE specification?
A. JMS
B. OLAP
C. ODBC
D. JTA

Question 5 – Objective 2 - J2EE Standard & General J2EE Concepts

Which of these J2EE standards defines a standard infrastructure to manage a device from Java
programs?
A. JMS
B. JMX
C. EJB
D. JTA
Question 6 – Objective 3 - Basic WebLogic Server Administration
Which of these is true about BEA WebLogic Server?
A. It is a Web Server
B. It is an Application Server
C. It has a Transaction Manager
D. All of the above

Question 7 – Objective 3 - Basic WebLogic Server Administration

Which of the following statements are true about WebLogic Server?
A. It is multithreaded
B. It is an instance of the weblogic.Server class executing within a JVM
C. It has a dedicated amount of RAM
D. None of the above

Question 8 – Objective 4 - J2EE Application Development/Deployment

The deployment descriptors within a WAR file resides in which directory?
A. WEB-INF
B. APP-INF
C. META-INF
D. MANIFEST

Question 9 – Objective 4 - J2EE Application Development/Deployment

Weblogic server supports which two of the following deployment methods?
A. Browser deployment.
B. Auto-deployment.
C. Command-line deployment.
D. Upload deployment

Question 10 – Objective 5 - JSP / Servlets

What is the default value for pageCheckSeconds with in a JSPServlet?
A. 0
B. 1
C. -1
D. 60

Question 11 – Objective 5 - JSP / Servlets

Which of the following is true about Objects stored in the request?
A. Are stored in javax.Servlet.jsp.request
B. Have the same lifespan as the client request.
C. Are available to all JSPs involved in processing the request; except JSPs accessed through
the
include and forward actions.
D. None

Question 12 – Objective 5 - JSP / Servlets

JavaBeans follow these conventions:
A. Should be Serializable
B. Public set & get methods for each attribute
C. A and B
D. None

Question 13 – Objective 5 - JSP / Servlets

Which of these methods in a ServletContextAttributeListener interface respond to attribute
change events?
A. attributeAdded()
B. attributeRemoved()
C. attributeReplaced()
D. All of the above

Question 14 – Objective 6 - JNDI

What does JNDI stand for?
A. Java Native Directory Interface
B. Java Naming and Directory Interface
C. Java Native Database Interface
D. None of the above

Question 15 – Objective 6 - JNDI

Consider this line of client code:
javax.naming.InitialContext ctx = new javax.naming.InitialContext();
Assuming that this code is used in a remote client, which statement is false?
A. The jndi.properties file is accessed during execution.
B. The exception javax.naming.NamingException can be thrown.
C. ctx will be a valid InitialContext always.
D. This code could generate an exception due to a network communication problem.

Question 16 – Objective 6 - JNDI

Which of these statements about JNDI is true?
i. Objects bound to a remote naming service must be serializable
ii. Objects are "copied" into and out of the naming service.
A. i
B. ii
C. i, ii
D. None of the above

Question 17 – Objective 7 - Database Connectivity (JDBC)

Which of these statements is true about JDBC?
A. JDBC stands for Java Database Connection Pool
B. It is a standard Java interface for accessing heterogeneous databases
C. It is a specification that defines three different driver types
D. All of the above

Question 18 – Objective 7 - Database Connectivity (JDBC)

Which of these statements loads a JDBC driver successfully?
A. Class.forName("com.pointbase.jdbc.jdbcUniversalDriver");
B. Class.forName("com:pointbase:jdbc:jdbcUniversalDriver");
C. Class.loadDriver("com.pointbase.jdbc.jdbcUniversalDriver");
D. Class.loadDriver("com:pointbase:jdbc:jdbcUniversalDriver");

Question 19 – Objective 8 - Developing Business Logic (EJB)

Consider the following scenario where pooling is not configured: A stateless session EJB
"InsuranceSession" has been deployed to production. At a given moment, 20 clients are
accessing this
EJB. How many instances should the server instantiate in order to cater to all clients at the same
moment
of time?
A. 20
B. Between 1 and 20
C. 1
D. Depends on EJB pool size setting

Question 20 – Objective 8 - Developing Business Logic (EJB)

In a financial application, each ATTEMPT to transfer a large amount of money is recorded,
specifying the
customer, the amount, and so on, by inserting the audit information into two separate databases.
This is
accomplished by two JDBC calls from a stateless session EJB.
The stateless session bean uses container-managed transactions to scope both database
operations in
one transaction. Even if the money transfer fails and is rolled back, the records of the attempted
transfer
must be stored in the two databases.
Which transaction attribute does the stateless session EJB require?
A. Required
B. Supports
C. Mandatory
D. RequiresNew

Question 21 – Objective 8 - Developing Business Logic (EJB)

An active Stateful Session Bean 'ShoppingCart' has opened a database connection. EJB
container
started to passivate eligible EJB instances. Which of these statements is true about EJB
passivation and
activation?
A. When 'ShoppingCart' methods are being invoked, the EJB container can passivate the EJB
safely
and later activate safely
B. 'ShoppingCart' can be passivated only when the configured <idle-timeout-seconds> in
META-INF\weblogic-ejb-jar.xml has exceeded
C. For safe EJB passivation and activation, the EJB developer needs to handle opening and
closing
database connections in ejbActivate() and ejbPassivate() methods respectively
D. Given the conditions, 'ShoppingCart' can never be passivated and activated safely

Question 22 – Objective 8 - Developing Business Logic (EJB)

A message-driven bean (MDB) is configured, in its deployment descriptor, to use a durable
subscription.
Which statement about the Bean is true?
A. The MDB does not set the client ID dynamically; the JMS connection factory sets it at run-time
B. The MDB could serve as a consumer in the point-to-point or publish-subscribe domain
C. The run-as-identity-principal must always be set
D. MDB can be associated with both queues and topics at the same time

Question 23 – Objective 8 - Developing Business Logic (EJB)

Two EJB objects 'ObjA' and 'ObjB' have been created exactly the same way, using the same EJB
Home
Interface 'ObjHome'. These objects are immediately compared using an "if" construct:
if (ObjA.isIdentical(ObjB))
{
//Some Java Code
}
A. This returns true for Stateless Session EJBs
B. This returns true for Stateful Session EJBs
C. Always true for Stateless Session EJBs and sometimes true for Stateful Session EJBs
D. Two EJBs cannot be compared using 'isIdentical' method

Question 24 – Objective 9 - Messaging

In WebLogic, a JMS server can be targeted to
A. Only the managed servers.
B. Only the administration server.
C. Only one server in a domain.
D. Any number of servers.

Question 25 – Objective 9 - Messaging

Which of these is a valid JMS domain?
i. Point-to-Point
ii. Peer-to-Peer
iii. Publish/Subscribe
A. i, ii
B. i, iii
C. i
D. ii, iii

Question 26 – Objective 10 - Transaction

From the following, which two are valid values for the <trans-attribute> tag for an EJB?
A. Never
B. Mandatory
C. Supports
D. Required

Question 27 – Objective 10 - Transaction

If an EJB must never be invoked within the context of a transaction, which of the <trans-
attribute>
tags must be specified within the EJB’s deployment descriptor?
A. NeverRequired
B. Never
C. NotSupported
D. NeverRequires

Question 28 – Objective 11 - Securing Enterprise Applications

J2EE declarative security,
A. is a means to describe an application's access control in a form that is external to the
application
B. involves defining security roles and constraints on web application resources
C. applies only to Web applications
D. implemented in XML-based deployment descriptors

Question 29 – Objective 11 - Securing Enterprise Applications

Consider the following XML code
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>login.jsp</form-login-page>
<form-error-page>error.jsp</form-error-page>
</form-login-config>
</login-config>
Which page will be served to the user if the user makes an invalid login attempt?
A. login.jsp
B. web.xml
C. error.jsp
D. error.html

Question 30 – Objective 12 - Develop and Deploy Web Services

Which one of these is not a web service standard?
A. UDMI
B. WSDL
C. SOAP
D. WS-Security

Question 31 – Objective 12 - Develop and Deploy Web Services

A web service may reference a service endpoint interface by using which of the following
annotations?
A. @WebService.endpoint
B. @WebService.endpointInterface
C. @endpointInterface
D. None of the above.

Question 32 – Objective 12 - Develop and Deploy Web Services

Which one of these standards is designed to be used as the basis for the construction of a wide
variety of
security models including PKI, Kerberos and SSL?
A. EJB-Security
B. WS-Security
C. JSP-Security
D. XML

Question 33 – Objective 12 - Develop and Deploy Web Services

If a JWS file does not implement a service endpoint interface, all public methods other than those
inherited from java.lang.Object will be exposed as web service operations. You can override
this
behavior by using which of the following annotations?
A. @WebMethod
B. @Method
C. @WebMethodInterface
D. @WebInterface

Question 34 – Objective 12 - Develop and Deploy Web Services

What does a web service generate if an error occurs during the processing of a request?
A. A Java Exception
B. java.io.Exception
C. A SOAP Fault
D. None of the above

Question 35 – Objective 13 - Performance Tuning

Which of these can impact performance in a production environment?
i. Suppressing Console Output
ii. Suppressing Username/Password
A. i
B. ii
C. i, ii
D. None of the above

Question 36 – Objective 13 - Performance Tuning

The use of which of these components can degrade the performance of a Container Managed
Entity
EJB?
A. Compound Keys
B. Foreign Keys
C. Primary Keys
D. Restrictive Keys

Question 37 – Objective 14 - Exception Handling

Which of these JSP directives is used to call another JSP when an exception occurs?
A. <%@ page error="myErrorPage.jsp" %>
B. <%@ page page="myErrorPage.jsp" %>
C. <%@ page errorPage="myErrorPage.jsp" %>
D. <%@ page exceptionPage="myErrorPage.jsp" %>

Question 38 – Objective 14 - Exception Handling

A stateless session Bean is implemented as a façade to multiple entity Beans, allowing for local
interface
invocation. During these invocations, which exception can be caught by the stateless session
Bean?
A. javax.ejb.EJBException
B. java.rmi.LocalException
C. java.rmi.RemoteException
D. javax.ejb.LocalException

Question 39 – Objective 15 - Eclipse

Which of these are valid subprojects of Eclipse?
A. Java Development Tools.
B. Web Tools Platform.
C. Data Tools Platform.
D. Deployment Tools.

Question 40 – Objective 15 - Eclipse

Which of these projects should be used while developing EJBs using Eclipse?
A. Dynamic Web Project
B. EJB Project
C. Java Project
D. Bean Project

Answers -
Question 1: Correct Answer: D
Question 2: Correct Answer: B, C
Question 3: Correct Answer: D
Question 4: Correct Answer: A, D
Question 5: Correct Answer: B
Question 6: Correct Answer: D
Question 7: Correct Answer: A, B, C
Question 8: Correct Answer: A
Question 9: Correct Answer: B, C
Question 10: Correct Answer: B
Question 11: Correct Answer: B
Question 12: Correct Answer: C
Question 13: Correct Answer: D
Question 14: Correct Answer: B
Question 15: Correct Answer: C
Question 16: Correct Answer: C
Question 17: Correct Answer: B
Question 18: Correct Answer: A
Question 19: Correct Answer: A
Question 20: Correct Answer: D
Question 21: Correct Answer: C
Question 22: Correct Answer: A
Question 23: Correct Answer: A
Question 24: Correct Answer: C
Question 25: Correct Answer: B
Question 26: Correct Answer: B, D
Question 27: Correct Answer: B
Question 28: Correct Answer: A, B, D
Question 29: Correct Answer: C
Question 30: Correct Answer: A
Question 31: Correct Answer: B
Question 32: Correct Answer: B
Question 33: Correct Answer: A
Question 34: Correct Answer: C
Question 35: Correct Answer: A
Question 36: Correct Answer: A
Question 37: Correct Answer: C
Question 38: Correct Answer: A
Question 39: Correct Answer: A, B, C
Question 40: Correct Answer: B

weblogic.Deployer Command-Line Reference

weblogic.Deployer is a Java-based deployment tool that provides a command-line

interface to the WebLogic Server deployment API. weblogic.Deployer is intended for
administrators and developers who want to perform interactive, command-line based
deployment operations.

See the WLST Command and Variable Reference for information about performing
deployment operations using the WebLogic Scripting Tool (WLST).

The following sections describe the weblogic.Deployer utility:

 Required Environment for weblogic.Deployer

 Syntax for Invoking weblogic.Deployer
• SSL Arguments
• Connection Arguments
• User Credentials Arguments
• Common Arguments
 Command Reference
 Example config.xml File and Corresponding weblogic.Deployer Command

Required Environment for weblogic.Deployer

To set up your environment to use the weblogic.Deployer utility:

1. Install and configure the WebLogic Server software, as described in the

WebLogic Server Installation Guide.

2. Add the WebLogic Server classes to the CLASSPATH environment variable, and
ensure that the correct JDK binaries are available in your PATH. You can use the
setWLSEnv.sh or setWLSEnv.cmd script, located in the server/bin subdirectory of
the WebLogic Server installation directory, to set the environment.

3. If you are connecting to an Administration Server via a configured Administration

channel, you must also configure SSL on the machine on which you run
weblogic.Deployer. See See Using the SSL Protocol to Connect to WebLogic
Server from weblogic.Admin in Managing WebLogic Security for instructions
about configuring SSL.

Syntax for Invoking weblogic.Deployer

java [SSL Arguments] weblogic.Deployer [Connection Arguments]
[User Credentials Arguments] COMMAND-NAME command-options
[Common Arguments]

Command names and options are not case-sensitive. See Command Reference for
detailed syntax and examples of using weblogic.Deployer commands.
SSL Arguments
java [ -Dweblogic.security.TrustKeyStore=DemoTrust ]
[ -Dweblogic.security.JavaStandardTrustKeystorePassPhrase=password
]
[ -Dweblogic.security.CustomTrustKeyStoreFileName=filename
-Dweblogic.security.TrustKeystoreType=CustomTrust
[-Dweblogic.security.CustomTrustKeystorePassPhrase=password ]
]
[ -Dweblogic.security.SSL.hostnameVerifier=classname ]
[ -Dweblogic.security.SSL.ignoreHostnameVerification=true ]
weblogic.Deployer
[ User Credentials Arguments ]
COMMAND-NAME command-arguments

If you have enabled the domain-wide administration port, or if you want to secure your
administrative request by using some other listen port that is secured by SSL, you must
include SSL arguments when you invoke weblogic.Deployer. Table 7-1 describes all
SSL arguments for the weblogic.Deployer utility.

Table 7-1 SSL Arguments Definition

Argument
-Dweblogic.security. Causes weblogic.Deployer to trust the CA certificates
TrustKeyStore=
DemoTrust in the demonstration trust keystore
(WL_HOME\server\lib\DemoTrust.jks).

This argument is required if the server instance to which

you want to connect is using the demonstration identity
and certificates.

By default, weblogic.Deployer trusts only the CA

certificates in the Java Standard Trust keystore
(SDK_HOME\jre\lib\security\cacerts).
-Dweblogic.security. Specifies the password that was used to secure the Java
JavaStandardTrustKeysto
rePassPhrase=password
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. Causes weblogic.Deployer to trust the CA certificates
CustomTrustKeyStoreFileNa
me=filename in a custom keystore that is located at filename. You
must use both arguments to trust custom keystores.
-Dweblogic.security.Trust
KeystoreType=CustomTrust
-Dweblogic.security.Custo Specifies the password that was used to secure the custom
mTrustKeystorePassPhrase=
password
 keystore.

You must use this argument only if the custom keystore is

protected by a password.
-Dweblogic.security.SSL. Specifies the name of a custom Host Name Verifier class.
hostnameVerifier=
classname The class must implement the
weblogic.security.SSL.HostnameVerifier interface.
-Dweblogic.security.SSL. Disables host name verification.
ignoreHostnameVerificat
ion=true

Connection Arguments
java [SSL Arguments] weblogic.Deployer
[-adminurl protocol://listen_address:port_number]
[User Credentials Arguments] COMMAND-NAME command-options [Common
Arguments]

Most weblogic.Deployer commands require you to specify the -adminurl arguments

described in Table 7-2 to connect to an Administration Server instance.

Table 7-2 Connection Arguments

Argument Definition
-adminurl The -adminurl value must specify the listen address and
[protocol://]Admin- listen port of the Administration Server.
Server-listen-
address:listen-port
To use a port that is not secured by SSL, the format is
-adminurl [protocol]Admin-Server-listen-
address:port where t3, http, iiop, and iiops are valid
protocols.

In order to use an adminurl with the HTTP protocol, you

must enable the HTTP tunneling option in the
Administration Console. For more information, see Setting
Up WebLogic Server for HTTP Tunneling in Designing
and Configuring WebLogic Server Environments. For
instructions on enabling HTTP tunneling in the
Administration Console, see Configure HTTP protocol in
Administration Console Online Help.

To use a port that is secured by SSL, the format is

-adminurl secure-protocol://Admin-Server-
listen-address:port where t3s and https are valid
secure protocols.

To connect to the Administration Server via a configured

Administration channel, you must specify a valid
administration port number: -adminurl secure-
protocol://Admin-Server-listen-address:domain-
 wide-admin-port

There is no default value for this argument.

User Credentials Arguments

java [ SSL Arguments ] weblogic.Deployer [Connection Arguments]
[ { -username username [-password password] } |
[ -userconfigfile config-file [-userkeyfile admin-key] ] ]
COMMAND-NAME command-options [Common Arguments]

Most weblogic.Deployer commands require you to specify the arguments in Table 7-3
to provide the user credentials of a WebLogic Server administrator.

Table 7-3 User Credentials Arguments

Argument Definition
-username The Administrator username. If you supply the -username option but
username
you do not supply a corresponding -password option,
weblogic.Deployer prompts you for the password.
-password The password of the Administrator user.
password

To avoid having the plain text password appear in scripts or in

process utilities such as ps, first store the username and encrypted
password in a configuration file using the STOREUSERCONFIG
command with weblogic.Admin. Omit both the -username and
-password options to weblogic.Deployer to use the values stored in
the default configuration file. See STOREUSERCONFIG in the
weblogic.Admin Command-Line Reference for more information on
storing and encrypting passwords.

If you want to use a specific configuration file and key file, rather
than the default files, use the -userconfigfile and -userkeyfile options
to weblogic.Deployer.
-userconfigfile Specifies the location of a user configuration file to use for the
config-file
administrative username and password. Use this option, instead of
the -user and -password options, in automated scripts or in
situations where you do not want to have the password shown on-
screen or in process-level utilities such as ps. Before specifying the
-userconfigfile option, you must first generate the file using the
weblogic.Admin STOREUSERCONFIG command as described in
STOREUSERCONFIG in the weblogic.Admin Command-Line
Reference.
-userkeyfile Specifies the location of a user key file to use for encrypting and
admin-key
decrypting the username and password information stored in a user
configuration file (the -userconfigfile option). Before specifying
the -userkeyfile option, you must first generate the key file using
 the weblogic.Admin STOREUSERCONFIG command as described in
STOREUSERCONFIG in the weblogic.Admin Command-Line
Reference.

Common Arguments

The common options described in Table 7-4 can be used with any of the commands
described in Command Reference.

Table 7-4 Common options for weblogic.Deployer

Option Name Description

-advanced Prints full command-line help text for all weblogic.Deployer actions
and options.
-debug Display debug messages in the standard output.
-examples Display example command lines for common tasks.
-help Prints command-line help text for the most commonly-used
weblogic.Deployer actions and options.

-noexit By default weblogic.Deployer calls System.exit(1) if an exception is

raised while processing a command. The exit value displayed indicates
the number of failures that occurred during the deployment operation.

The -noexit option overrides this behavior for batch processing.

-noversion Indicates that weblogic.Deployer should ignore all version related code
paths on the Administration Server. This behavior is useful when
deployment source files are located on Managed Servers (not the
Administration Server) and you want to use the external_stage staging
mode.

If you use this option, you cannot use versioned applications.

-nowait weblogic.Deployer prints the task ID and exits without waiting for the
action to complete. This option is used to initiate multiple tasks and then
monitor them later with the -list action.
-output <raw (Deprecated.) Specify either raw or formatted to control the appearance
| formatted>
of weblogic.Deployer output messages. Both output types contain the
same information, but raw output does not contain embedded tabs. By
default, weblogic.Deployer displays raw output.
-purgetasks Indicates that weblogic.Deployer should flush out deployment tasks
that are retired.
-remote Indicates that weblogic.Deployer is not running on the same machine
as the Administration Server, and that source paths specified in the
command are valid for the Administration Server machine itself. If you
do not use the -remote option, weblogic.Deployer assumes that all
source paths are valid paths on the local machine.
-timeout Specifies the maximum time, in seconds, to wait for the deployment task
seconds
to complete. After the time expires, weblogic.Deployer prints out the
current status of the deployment and exits.
-verbose Displays additional progress messages, including details about the
prepare and activate phases of the deployment.
-version Prints version information for weblogic.Deployer.

Command Reference

The following sections describe the weblogic.Deployer commands and command

options used to perform deployment tasks with WebLogic Server:

 Cancel
 Deploy
 Distribute
 Listapps
 List, Listtask
 Redeploy
 Start
 Stop
 Undeploy
 Update

Note: weblogic.Deployer commands are displayed in bold type to distinguish them

from command options.

Cancel

Attempt to cancel a running deployment task.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-cancel task_id
[Common Arguments]
Argument or Definition
Option
task_id The identifier of the deployment task to cancel. The identifier can be
specified by using the id option with the deploy, distribute, update,
undeploy, redeploy, stop, and start commands.

Examples

The following command starts a deployment operation and specifies the task identifier,
myDeployment:
java weblogic.Deployer -adminurl http://localhost:7001
-username weblogic -password weblogic
-deploy ./myapp.ear -id myDeployment

If the deployment task has not yet completed, the following command attempts to cancel
the deployment operation:

java weblogic.Deployer -adminurl http://localhost:7001

-username weblogic -password weblogic
-cancel -id myDeployment

Deploy

Deploys or redeploys an application or module.

Note: The -ACTIVATE command, an alias for -deploy, is deprecated.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-deploy [[-name] deployment_name] [-source] file
[-plan file] [-targets target_list] [-submoduletargets
target_list]
[-upload]
[-stage | -nostage | -external_stage]
[-retiretimeout seconds]
[-library [-libspecver version] [-libimplver version]]
[-altappdd file] [-altwlsappdd file]
[-securityModel] [-enableSecurityValidation]
[-id task_id]
[Common Arguments]
Argument or Option Definition
-name deployment_name Specifies the deployment name to assign to a newly-
deployed application or stand-alone module.

Both the -name option and deployment_name argument

are optional, as described in the Syntax. If a deployment
name is not explicitly identified with the -deploy
command, the name is derived from the specified
deployment file or directory:

 For an archive file, the default deployment name

is the name of the archive file without the file
extension (myear for the file myear.ear).

 For an exploded archive directory, the default

deployment name is the name of the top-level
directory.

 If you specify an application installation root

directory, the default deployment name is derived
from the archive filename or exploded archive
 directory name in the /app subdirectory.
-source file Specifies the archive file or exploded archive directory to
deploy. You can omit the -source option and supply
only the file or directory to deploy.
-plan file Specifies a deployment plan to use when deploying the
application or module. By default, weblogic.Deployer
does not use an available deployment plan, even if you
are deploying from an application root directory that
contains a plan.
-targets target_list Specifies the targets on which to distribute and deploy the
application or module.

The target_list argument is a comma-separated list of

the target servers, clusters, or virtual hosts. Each target
may be qualified with a J2EE module name
(<module1>@<server1>). This enables you to deploy
different modules of an Enterprise Application to
different servers or clusters.

If you do not specify a target list with the -deploy

command, the target defaults to:

 the Administration Server instance for new

deployments.

 the application's current targets for deployed

applications.
-submoduletargets Specifies JMS Server targets for resources defined within
target_list
a JMS application module. See Using Sub-Module
Targeting with JMS Application Modules and Using
WLST to Manage JMS Servers and JMS System
Resources in Configuring and Managing WebLogic JMS.
-upload Transfers the specified deployment files, including
deployment plans and alternate deployment descriptors,
to the Administration Server. Use this option when you
are on a remote machine and you cannot copy the
deployment files to the Administration Server by other
means. The application files are uploaded to the
WebLogic Server Administration Server's upload
directory prior to distribution and deployment.
-stage | -nostage | Specifies a staging mode to use when deploying or
-external_stage
distributing an application:

 -stage—Copies deployment files to target

servers' staging directories. stage is the default
mode used when deploying or distributing to
 Managed Server targets.

 -nostage—Does not copy the deployment files to

target servers, but leaves them in a fixed location,
specified by the -source option. Target servers
access the same, copy of the deployment files.
nostage is the default used when deploying or
distributing to the Administration Server (for
example, in a single-server domain).

 -external_stage—Does not copy the

deployment files to target servers; instead, you
must ensure that deployment files have been
copied to the correct subdirectory in the target
servers' staging directories. You can manually
copy the files or use a third-party tool or script.

See Controlling Deployment File Copying with Staging

Modes.

-retiretimeout seconds Specifies the number of seconds before WebLogic Server

undeploys the currently-running version of this
application or module. See Redeploying a New Version
of an Application.

-library Identifies the deployment as a shared J2EE library or

optional package. You must include the -library option
when deploying or distributing any J2EE library or
optional package. See Deploying Shared J2EE Libraries
and Dependent Applications.

-libspecver version Provides the specification version of a J2EE library or

optional package. This option can be used only if the
library or package does not include a specification
version in its manifest file. -libversion can be used
only in combination with -library. See Registering
Libraries with WebLogic Server.

-libimplver version Specifies the implementation version of a J2EE library or

optional package. This option can be used only if the
library or package does not include a implementation
version in its manifest file. -libimplversion can be
used only in combination with -library. See Registering
 Libraries with WebLogic Server.

-usenonexclusivelock Indicates that the deployment operation will use an

existing lock, already acquired by the same user, on the
domain. This is useful the use is using multiple
deployment tools simultaneously and one of the tools has
already acquired a lock on the domain configuration.
-altappdd file (Deprecated.) Specifies the name of an alternate J2EE
deployment descriptor (application.xml) to use for
deployment.
-altwlsappdd file (Deprecated.) Specifies the name of an alternate
WebLogic Server deployment descriptor (weblogic-
application.xml) to use for deployment.
-securityModel Specifies the security model to use for this deployment.
[ DDOnly | CustomRoles |
CustomRolesAndPolicy |
Advanced ]
-enableSecurityValidation Specifies whether or not to enable validation of security
data.
-id task_id Specifies the task identifier of a running deployment task.
You can specify an identifier with the -deploy,
-redeploy, or -undeploy commands, and use it later as
an argument to the -cancel or -list commands. Make sure
that the identifier is unique to all other running
deployment tasks. The system automatically generates a
unique identifier if you do not specify one.

Examples

See the following sections for examples of using the -deploy command:

 Deploying to a Single-Server Domain

 Deploying an Application with a Deployment Plan
 Uploading Deployment Files from a Remote Client
 Deploying to One or More Targets
 Deploying to a Cluster Target
 Using Module-Level Targeting for Deploying an Enterprise Application
 Targeting Application-Scoped JMS, JDBC, and WLDF Modules
 Using Sub-Module Targeting with JMS Application Modules
 Using Nostage Mode Deployment
 Using Stage Mode Deployment
 Using External_stage Mode Deployment
 Distributing Applications to a Production Environment
 Registering Libraries with WebLogic Server
 Deploying Applications That Reference Libraries
Distribute

Prepares deployment files for deployment by copying deployment files to target servers
and validating them.

A distributed application can be quickly started by using the Start command. You can
start the application in Administration mode, or make it available to Administration and
client requests. While in Administration mode, the application can be accessed only by
internal clients via a configured Administration port. External clients cannot access the
application.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-distribute [[-name] deployment_name] [-source] file
[-plan file] [-targets target_list] [-submoduletargets
target_list]
[-upload]
[-stage | -nostage | -external_stage]
[-library [-libspecver version] [-libimplver version]]
[-altappdd file] [-altwlsappdd file]
[-securityModel] [-enableSecurityValidation]
[-id task_id]
[Common Arguments]
Argument or Option Definition
-name deployment_name Specifies the deployment name to assign to the
distributed application or module.

Both the -name option and deployment_name argument

are optional, as described in the Syntax. If a deployment
name is not explicitly identified, a name is derived from
the specified deployment file or directory:

 For an archive file, the default deployment name

is the name of the archive file without the file
extension (myear for the file myear.ear).

 For an exploded archive directory, the default

deployment name is the name of the top-level
directory.

 If you specify an application installation root

directory, the default deployment name is derived
from the archive filename or exploded archive
directory name in the /app subdirectory.
-source file Specifies the archive file or exploded archive directory to
distribute. You can omit the -source option and supply
only the file or directory.
-plan file Specifies a deployment plan to distribute with the
application or module, used to configure the application.
-targets target_list Specifies the targets on which to distribute the application
or module.

The target_list argument is a comma-separated list of

the target servers, clusters, or virtual hosts. Each target
may be qualified with a J2EE module name
(<module1>@<server1>). This enables you to distribute
different modules of an Enterprise Application to
different servers or clusters.

If you do not specify a target list with the -deploy

command, the target defaults to:

 the Administration Server instance for new

deployments.

 the application's current targets for deployed

applications.
-submoduletargets Specifies JMS Server targets for resources defined within
target_list
a JMS application module. See Using Sub-Module
Targeting with JMS Application Modules and Using
WLST to Manage JMS Servers and JMS System
Resources in Configuring and Managing WebLogic JMS.
-upload Transfers the specified deployment files, including any
specified deployment plans, to the Administration Server
before distribution. Use this option when you are on a
remote machine and you cannot copy the deployment
files to the Administration Server by other means. The
application files are uploaded to the WebLogic Server
Administration Server's upload directory prior to
distribution.
-stage | -nostage | Specifies a staging mode to use when deploying or
-external_stage
distributing an application:

 -stage—Copies deployment files to target

servers' staging directories. stage is the default
mode used when deploying or distributing to
Managed Server targets.

 -nostage—Does not copy the deployment files to

target servers, but leaves them in a fixed location,
specified by the -source option. Target servers
access the same, copy of the deployment files.
nostage is the default used when deploying or
distributing to the Administration Server (for
example, in a single-server domain).

 -external_stage—Does not copy the

deployment files to target servers; instead, you
 must ensure that deployment files have been
copied to the correct subdirectory in the target
servers' staging directories. You can manually
copy the files or use a third-party tool or script.

See Controlling Deployment File Copying with Staging

Modes.

-library Identifies the deployment as a shared J2EE library or

optional package. You must include the -library option
when deploying or distributing any J2EE library or
optional package. See Deploying Shared J2EE Libraries
and Dependent Applications.

-libspecver version Provides the specification version of a J2EE library or

optional package. This option can be used only if the
library or package does not include a specification
version in its manifest file. -libversion can be used
only in combination with -library. See Registering
Libraries with WebLogic Server.

-libimplver version Specifies the implementation version of a J2EE library or

optional package. This option can be used only if the
library or package does not include a implementation
version in its manifest file. -libimplversion can be
used only in combination with -library. See Registering
Libraries with WebLogic Server.

-altappdd file (Deprecated.) Specifies the name of an alternate J2EE

deployment descriptor (application.xml) to use for
deployment or distribution.
-altwlsappdd file (Deprecated.) Specifies the name of an alternate
WebLogic Server deployment descriptor (weblogic-
application.xml) to use for deployment or distribution.
-securityModel Specifies the security model to be used for this
[ DDOnly |
CustomRoles |
application.
CustomRolesAndPolicy
|
Advanced ]
-enableSecurityValidation Specifies whether or not to enable validation of security
data.
-id task_id Specifies the task identifier of a running deployment task.
 You can specify an identifier with the -deploy,
-redeploy, or -undeploy commands, and use it later as
an argument to the -cancel or -list commands. Make sure
that the identifier is unique to all other running
deployment tasks. The system automatically generates a
unique identifier if you do not specify one.

Examples

The -distribute command operates similar to -deploy, but WebLogic Server does not
start the application or module on target servers. See the examples links for the Deploy
command for more information.

Listapps

Lists the deployment names for applications and stand-alone modules deployed,
distributed, or installed to the domain.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-listapps
[Common Arguments]

Examples

See Displaying Version Information for Deployed Applications.

List, Listtask

Displays the status of deployment tasks currently running in the domain.

Syntax
java [SSL Arguments] weblogic.Deployer Connection Arguments
[User Credentials Arguments] <-list | -listtask> [task_id]
[Common Arguments]
Argument or Definition
Option
task_id The identifier of a deployment task to display. The identifier can be
specified by using the -id argument to the DEPLOY, DISTRIBUTE,
UPDATE, UNDEPLOY, REDEPLOY, STOP, and START commands.

Examples

See Managing Long-Running Deployment Tasks.

Redeploy
Redeploys a running application or part of a running application.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-redeploy [[-name] deployment_name] {-source file | filelist}
[-plan file] [-targets target_list] [-submoduletargets
target_list]
[-upload]
[-delete_files]
[-retiretimeout seconds] [-id task_id]
[Common Arguments]
Argument or Option Definition
-name Specifies the deployment name of a deployed application or
deployment_name
module. The -name option can be omitted, in which case the name
is taken from the -source file argument.
-source file Specifies the archive file or exploded archive directory to
distribute, deploy, or redeploy.

When used with the redeploy command, the -source option

specifies the location of new deployment files to redeploy, for
example, when updating an application to a new version.

To specify multiple files for a partial redeployment, omit the

-source option and supply only a filelist.

Note: Use a file or filelist specification only for redeploying

static files within a J2EE module. To redeploy an entire J2EE
module within an Enterprise Application, use the module-targeting
syntax, -targets module@target, described in Using Partial
Redeployment for J2EE Module Updates.
filelist Specifies one or more files to redeploy. If the filelist specifies
multiple files, the redeployment is treated as a partial redeployment
of the specified files.

Note: Use a file or filelist specification only for redeploying

static files within a J2EE module. To redeploy an entire J2EE
module within an Enterprise Application, use the module-targeting
syntax, -targets module@target, described in Using Partial
Redeployment for J2EE Module Updates.

The use of -redeploy module-uri is deprecated. Instead, use

production redeployment or redeploy the module using the
-targets module@target syntax.
-plan file Specifies a deployment plan to use when distributing, deploying, or
redeploying.

When redeploying an application, the -plan option allows you to

specify an updated configuration to use during the redeployment. If
 the revised deployment plan contains changes to resource bindings,
WebLogic Server attempts to redeploy a new version of the
application alongside an older version. See Updating the
Deployment Configuration for an Application.
-targets Specifies the targets on which to distribute, deploy, or redeploy the
target_list
application or module.

The target_list argument is a comma-separated list of the target

servers, clusters, or virtual hosts. Each target may be qualified with
a J2EE module name (<module1>@<server1>). This enables you
to redeploy different modules of an Enterprise Application to
different servers or clusters.

If you do not specify a target list with the -deploy command, the
target defaults to:

 the Administration Server instance for new deployments.

 the application's current targets for deployed applications.

If you do not specify a target list with the -redeploy command, the
application is redeployed on all of its current target servers.
-submoduletargets Specifies JMS Server targets for resources defined within a JMS
target_list
application module. See Using Sub-Module Targeting with JMS
Application Modules and Using WLST to Manage JMS Servers
and JMS System Resources in Configuring and Managing
WebLogic JMS.
-upload Transfers the specified deployment files, including deployment
plans and alternate deployment descriptors, to the Administration
Server. Use this option when you are on a remote machine and you
cannot copy the deployment files to the Administration Server by
other means. The application files are uploaded to the WebLogic
Server Administration Server's upload directory prior to
distribution and deployment.

Use the -upload option with the REDEPLOY command when you
are upgrading an application to a new version.
-delete_files Removes static files from a server's staging directory.
delete_files is valid only for unarchived deployments, and only
for applications deployed using -stage mode. You must specify
target servers when using this option, as shown in the following
example:

java weblogic.Deployer -adminurl http://myserver:7001

-username weblogic
-password weblogic -name myapp
-targets myapp@myserver -redeploy
 -delete_files myapp/tempindex.html

delete_files only removes files that WebLogic Server copied to

the staging area during deployment. If you use the delete_files
option with an application that was deployed using either
-nostage or -external_stage mode, the command does not
delete the files.

delete_files can only be used in combination with the -redeploy

command.

Note: Because the -delete_files option deletes all specified files or,
if you specify a directory but do not specify files within the
directory, all files in the specified directory, BEA recommends that
you use caution when using the delete_files option and that you do
not use the delete_files option in production environments.
-retiretimeout Specifies the number of seconds before WebLogic Server
seconds
undeploys the currently-running version of this application or
module. See Redeploying a New Version of an Application.

-id task_id Specifies the task identifier of a running deployment task. You can
specify an identifier with the -deploy, -redeploy, or -undeploy
commands, and use it later as an argument to the -cancel or -list
commands. Make sure that the identifier is unique to all other
running deployment tasks. The system automatically generates a
unique identifier if you do not specify one.

Examples

See the following sections for examples of using the -redeploy command:

 Redeploying a New Version of an Application

 Rolling Back the Production Redeployment Process
 Steps for Distributing a New Version of an Application
 Redeploying Applications and Modules In-Place
 Using Partial Redeployment for J2EE Module Updates
 Updating Static Files in a Deployed Application

Start

Makes a stopped (inactive) application available to clients on target servers. -start does
not redistribute deployment files to target servers. Optionally, with the -adminmode
option, starts the application in Administration mode, which makes it available only via a
configured Administration channel. In order to issue a -start command, the files must
already be available via an earlier -deploy or -distribute command.

Note: The -activate command, an alias for -start, is deprecated.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-start [-adminmode] [-name] deployment_name
[-appversion version] [-planversion version]
[-targets target_list] [-submoduletargets target_list]
[-retiretimeout seconds]
[-id task_id]
[Common Arguments]
Argument or Option Definition
-adminmode Indicates that the application should start in Administration mode,
not Production mode (which is the default).
-name Specifies the deployment name of a deployed application or
deployment_name
module. The -name option can be omitted, in which case the name
is taken directly from the deployment_name. (If the
deployment_name specifies a file or directory name, the
deployment name is derived from the file specification.)
-appversion The version of the application to start.
version
-planversion The version of the deployment plan to use when starting the
version
application.
-targets Specifies the targets on which to DISTRIBUTE, DEPLOY, REDEPLOY,
target_list
or START the application or module.

The target_list argument is a comma-separated list of the target

servers, clusters, or virtual hosts. Each target may be qualified with
a J2EE module name (<module1>@<server1>). This enables you
to deploy different modules of an Enterprise Application to
different servers or clusters.

If you do not specify a target list with the -deploy command, the
target defaults to:

 the Administration Server instance for new deployments.

 the application's current targets for deployed applications.

If you do not specify a target list with the -redeploy or -start

commands, the command is performed on all of the application's
current targets.
-submoduletargets Specifies JMS Server targets for resources defined within a JMS
target_list
application module. See Using Sub-Module Targeting with JMS
Application Modules and Using WLST to Manage JMS Servers
and JMS System Resources in Configuring and Managing
WebLogic JMS.
-retiretimeout Specifies the number of seconds before WebLogic Server
seconds
undeploys the currently-running version of this application or
module. See Redeploying a New Version of an Application.
-id task_id Specifies the task identifier of a running deployment task. You can
specify an identifier with the -distribute, -deploy, -redeploy,
-start, or -undeploy commands, and use it later as an argument to
the -cancel or -list commands. Make sure that the identifier is
unique to all other running deployment tasks. The system
automatically generates a unique identifier if you do not specify
one.

Examples

See the following sections for examples of using the -start command:

 Starting a Distributed Application

 Making an Application Available to Clients
 Stopping an Application to Restrict Client Access

Stop

Makes an application inactive and unavailable administration and client requests. All of
the application's staged files remain available on target servers for subsequent -start,
-deploy, -redeploy, or -undeploy actions. You can optionally choose to stop the
application only to client requests by placing it in Administration mode with the
-adminmode option. While in Administration mode, the application be accessed only via
a configured Administration channel.

Note: The -deactivate command, an alias for -stop, is deprecated.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-stop [-adminmode] [-name] deployment_name
[-appversion version] [-planversion version]
[-targets target_list] [-submoduletargets target_list]
[-ignoresessions] [-graceful]
[-id task_id]
[Common Arguments]
Argument or Option Definition
-adminmode Indicates that a running application should switch to
Administration mode and accept only Administration requests via
a configured Administration channel. If this option is not specified,
the running application is stopped and cannot accept
Administration or client requests until is it restarted.
-name Specifies the deployment name of a deployed application or
deployment_name
module. The -name option can be omitted, in which case the name
is taken directly from the deployment_name. (If the
deployment_name specifies a file or directory name, the
 deployment name is derived from the file specification.)
-appversion The version identifier of the deployed application.
version
-planversion The version identifier of the deployment plan.
version
-targets Specifies the targets on which to -distribute, -deploy, -redeploy,
target_list
-start, or -stop the application or module.

The target_list argument is a comma-separated list of the target

servers, clusters, or virtual hosts. Each target may be qualified with
a J2EE module name (<module1>@<server1>). This enables you
to deploy different modules of an Enterprise Application to
different servers or clusters.

If you do not specify a target list with the -deploy command, the
target defaults to:

 the Administration Server instance for new deployments.

 the application's current targets for deployed applications.

If you do not specify a target list with the -redeploy, -start, or

-stop commands, the command is performed on all of the
application's current targets.
-submoduletargets Specifies JMS Server targets for resources defined within a JMS
target_list
application module. See Using Sub-Module Targeting with JMS
Application Modules and Using WLST to Manage JMS Servers
and JMS System Resources in Configuring and Managing
WebLogic JMS.
-graceful Stops the application after existing HTTP clients have completed
their work. If you do not specify the -graceful option, WebLogic
Server immediately stops the application or module. See Taking a
Production Application Offline.

-ignoresessions This option immediately places the application into Administration

mode without waiting for current HTTP sessions to complete.

-id task_id Specifies the task identifier of a running deployment task. You can
specify an identifier with the -distribute, -deploy, -redeploy,
-start, -stop, or -undeploy commands, and use it later as an
argument to the -cancel or -list commands. Make sure that the
identifier is unique to all other running deployment tasks. The
system automatically generates a unique identifier if you do not
specify one.
Examples

See the following sections for examples of using the -stop command, see Stopping an
Application to Restrict Client Access.

Undeploy

Stops the deployment unit and removes staged files from target servers.

Note: The -REMOVE command, an alias for -undeploy, is deprecated.

Warning: When you undeploy an application that contains application-scoped resources,

the resources are deleted along with the application, which can potentially cause
abandoned transactions or lost messages as a result of deleted JMS destinations. For more
information, see Unregister Resource Grace Period in Programmikng WebLogic JTA.

Warning: You should only undeploy applications that you are certain you want to
completely remove; to temporarily stop client access to applications, use the -stop
command, described in weblogic.Deployer Command-Line Reference, instead.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-undeploy [-name] deployment_name
[-appversion version] [-planversion version]
[-targets target_list] [-submoduletargets target_list]
[-graceful] [-ignoresessions]
[-id task_id]
[Common Arguments]
Argument or Option Definition
-name Specifies the deployment name of a deployed application or
deployment_name
module. The -name option can be omitted, in which case the name
is taken directly from the deployment_name. (If the
deployment_name specifies a file or directory name, the
deployment name is derived from the file specification.)
-appversion The version identifier of the deployed application.
version
-planversion The version identifier of the deployment plan.
version
-targets Specifies the targets from which the application or module are
target_list
undeployed.

Note: Any target not included in the target list is not removed.

The target_list argument is a comma-separated list of the target

servers, clusters, or virtual hosts. Each target may be qualified with
a J2EE module name (<module1>@<server1>). This enables you
to undeploy different modules of an Enterprise Application from
 different servers or clusters.
-submoduletargets Specifies the JMS resources to be undeployed.
target_list

Note: Any sub-module target not included in the target list is not
removed.

See Using Sub-Module Targeting with JMS Application Modules

and Using WLST to Manage JMS Servers and JMS System
Resources in Configuring and Managing WebLogic JMS
-graceful Stops the application after existing HTTP clients have completed
their work. If you do not specify the -graceful option, WebLogic
Server immediately stops the application or module. See Taking a
Production Application Offline.

The module is undeployed after it is stopped.

-ignoresessions Immediately stops and undeploys the application without waiting
for current HTTP sessions to complete.
-id task_id Specifies the task identifier of a running deployment task. You can
specify an identifier with the -distribute, -deploy, -redeploy,
-start, -stop, or -undeploy commands, and use it later as an
argument to the -cancel or -list commands. Make sure that the
identifier is unique to all other running deployment tasks. The
system automatically generates a unique identifier if you do not
specify one.

Examples

See the following sections for examples of using the -undeploy command:

 Undeploying an Application or Module

 Sub-module Targeting for Stand-alone JMS Modules

Update

Updates an application's deployment plan by redistributing the plan files and

reconfiguring the application based on the new plan contents.

Note: -update cannot be used to update an application's resource bindings. To update the
resource bindings for an application, you must use the Redeploy command.

Syntax
java [SSL Arguments] weblogic.Deployer
Connection Arguments [User Credentials Arguments]
-update -plan deployment_plan [-name] deployment_name
[-appversion version] [-planversion version]
[-targets target_list] [-submoduletargets target_list]
 [-upload] [-id task_id]
[Common Arguments]
Argument or Option Definition
-plan Identifies the deployment plan to use for updating the application's
deployment_plan configuration. The specified deployment plan must be valid for the
application's target servers. For example, the plan cannot contain
null variables for required resources unless those resources were
previously defined in the associated desrciptor.

Update operations update only those descriptors for which there is

a changed, not null value in the deployment plan. If a plan that is
used by an update operation contains null variables, the current
values in the corresponding descriptors are not updated.
-name Specifies the deployment name of a deployed application or
deployment_name
module. The -name option can be omitted, in which case the name
is taken directly from the deployment_name. (If the
deployment_name specifies a file or directory name, the
deployment name is derived from the file specification.)
-appversion The version identifier of the deployed application.
version
-planversion The version identifier of the deployment plan.
version
-targets Specifies the targets on which to -distribute, -deploy, -redeploy,
target_list
-undeploy, -start, or -stop the application or module.

The target_list argument is a comma-separated list of the target

servers, clusters, or virtual hosts. Each target may be qualified with
a J2EE module name (<module1>@<server1>). This enables you
to deploy different modules of an Enterprise Application to
different servers or clusters.

If you do not specify a target list with the -deploy command, the
target defaults to:

 the Administration Server instance for new deployments.

 the application's current targets for deployed applications.

If you do not specify a target list with the -redeploy, -undeploy,

-start, or -stop commands, the command is performed on all of the
application's current targets.
-submoduletargets Specifies JMS Server targets for resources defined within a JMS
target_list
application module. See Using Sub-Module Targeting with JMS
Application Modules and Using WLST to Manage JMS Servers
and JMS System Resources in Configuring and Managing
WebLogic JMS.
-upload Uploads a new deployment plan to the Administration Server
before updating the application.
-id task_id Specifies the task identifier of a running deployment task. You can
specify an identifier with the -distribute, -deploy, -redeploy,
-update, -start, -stop, or -undeploy commands, and use it later as
an argument to the -cancel or -list commands. Make sure that the
identifier is unique to all other running deployment tasks. The
system automatically generates a unique identifier if you do not
specify one.

Example

See Updating an Application to Use a Different Deployment Plan

Example config.xml File and Corresponding weblogic.Deployer Command

This section demonstrates an application's config.xml file and the corresponding

weblogic.Deployer command to deploy the application.

Assuming:

 mycluster is a cluster name

 D1C2S1 and D1C2S2 are server names
 RemoteJMSServer1 and RemoteJMSServer2 are JMS server names

The application's config.xml file would contain:

<AppDeployment
Name="dd-remote-cluster"
SourcePath="./udd-debug-deployment-on-remote-cluster-jms.xml"
Targets="mycluster">
<SubDeployment Name="RemoteCluster" Targets="mycluster"/>
<SubDeployment Name="D1C2S2" Targets="D1C2S2"/>
<SubDeployment Name="RemoteClusterServers" Targets="D1C2S1,D1C2S2"/>
<SubDeployment Name="RemoteClusterJMSServers"
Targets="RemoteJMSServer1,RemoteJMSServer2"/>
<SubDeployment Name="RemoteQueue1" Targets="RemoteJMSServer1"/>
</AppDeployment>

The weblogic.Deployer -deploy command to deploy the application would be:

java weblogic.Deployer -adminurl t3://MySystem:10000 -username system

-password system -name dd-remote-cluster
-deploy "config\jms\udd-debug-deployment-on-remote-cluster-jms.xml"
-targets mycluster -submoduletargets RemoteCluster@mycluster,
D1C2S2@D1C2S2, RemoteClusterServers@D1C2S1,
RemoteClusterServers@D1C2S2, RemoteClusterJMSServers@RemoteJMSServer1,
RemoteClusterJMSServers@RemoteJMSServer2, RemoteQueue1@RemoteJMSServer1

Creating a New WebLogic Domain

Before you can develop and run WebLogic-based applications, you must first create a
domain. The Configuration Wizard guides you through the process of creating a new
domain quickly and easily, by selecting the product components you want to include in
your domain, or by using domain templates.

The following topics describe the steps required to create a new domain using the
Configuration Wizard:

 Create or Extend a Domain

 Select a Domain Source
 Configure an Administrator Username and Password
 Specify the Server Start Mode and JDK
 Customize Environment and Services Settings
 Create the WebLogic Domain
 Creating Domain

Related Topics

Overview of Creating a New Domain Using the Configuration Wizard

Introduction to Domains

Creating a New Domain

Create or Extend a Domain

The Welcome window prompts you to choose whether you want to create a new domain
or extend an existing one.

Choose this When you want to . . .

option . . .
Create a new Create a new domain that is configured to meet your requirements. Begin
WebLogic by selecting the product components you want to include in your domain,
domain or a domain template to be used as the basis for your domain. Then
modify settings as required.
Extend an Add product component functionality or support for additional
existing applications and services to an existing domain. Begin by selecting the
WebLogic directory of the domain that you want to update. Then specify the product
domain components you want to add, or identify the extension template you want
to use for adding applications and services. You then have the option of
customizing the JDBC connections to your database and the JMS file
store, if defined. To learn more, see Extending Domains.

Related Topics

Overview of Creating a New Domain Using the Configuration Wizard

Introduction to Domains
Creating a New Domain

Select a Domain Source

The Select a Domain Source window prompts you to select the source from which to
create the domain. You can select the product components to include in your domain, or
select a custom template on which to base your domain.

Choose one of the following options for selecting the source for your domain:

 Generate a domain configured automatically to support the following BEA

products:

To use this option, select the check boxes associated with the components you
want to include, and click Next.

 Base this domain on an existing template

To use this option, manually enter the full pathname to the template in the
Template location field and click Next, or click Browse to navigate to the
directory containing the desired template. Select the domain template that
contains the settings you want to use as the basis for your domain.

Note: While using the Configuration Wizard or WLST Offline to create or extend
a clustered domain with a template that has applications containing application-
scoped JDBC and/or JMS resources, you may need to perform additional steps
(after the domain is created or extended) to make sure that the application and its
application-scoped resources are targeted and deployed properly in a clustered
environment. For more information on the targeting and deployment of
application-scoped modules, see "Deploying Applications and Modules" in
Deploying Applications to WebLogic Server at the following URL:

http://e-docs.bea.com/wls/docs90/deployment/deploy.html

Configure an Administrator Username and Password

The Configure Administrator Username and Password window prompts you to

specify a username and password to be used for starting the Administration Server.

To configure an administrator username and password:

1. Enter a valid value in the Username field. This name is used to boot the
Administration Server and connect to it.

Do not use commas, tabs, or any characters in the following comma-separated

list: < >, #, |, &, ?, ( ), { }. User names are case sensitive.

2. Enter a valid value in the User password field: a string of at least 8 case-sensitive
characters. The password value is encrypted.
 Note: Do not use the name/password combination weblogic/weblogic in a
production environment.

3. Reenter the password in the Confirm user password field.

4. Optionally, enter a login description for this username.

5. Click Next to proceed to the next configuration window.

Specify the Server Start Mode and JDK

The Configure Server Start Mode and JDK window prompts you to specify the:

 Startup mode for your domain

 JDK to be used for the domain

Choose the Startup Mode

Specify the startup mode for your domain as shown in the following table.

Choose this When . . .

mode . . .
Development You are creating your applications. In this mode, the configuration of
security is relatively relaxed, allowing you to auto-deploy applications.
Production Your application is running in its final form. In this mode, security is
fully configured.

Differences Between Domain Startup Modes

The following table describes the differences between development and production
modes in terms of key functions.

Table 3-1 In development mode . . . In production mode . . .

Differences
Between
Development
and
Production
Modes

Function
SSL You can use the demonstration digital You should not use the
certificates and the demonstration keystores demonstration digital
provided by the WebLogic Server security certificates and the
services. With these certificates, you can demonstration keystores. If
design your application to work within you do so, a warning message
environments secured by SSL. is displayed.
 For more information about managing
security, see "Configuring SSL" in
Securing WebLogic Server at the following
URL:

http://e-docs.bea.com/wls/docs90/
secmanage/ssl.html
Deploying WebLogic Server instances can The auto-deployment feature is
Applications automatically deploy and update disabled, so you must use the
applications that reside in the WebLogic Server
domain_name/autodeploy directory Administration Console, the
(where domain_name is the name of a weblogic.Deployer tool, or
domain). the WebLogic Scripting Tool
(WLST). For more
It is recommended that this method be used information, see Deploying
only in a single-server development Applications to WebLogic
environment. Server at the following URL:

For more information, see "Auto- http://e-docs.bea.com/wls/

Deploying Applications in Development docs90/deployment/index.html
Domains" in Deploying Applications to
WebLogic Server at the following URL:

http://e-docs.bea.com/wls/
docs90/deployment/deploy.html#autodeplo
y
Log File When you start a server, the server A server rotates its local log
Rotation automatically renames (rotates) its local file after the size of the file
server log file as server-name.log.n. For reaches 500 kilobytes.
the remainder of the server session, the
server rotates its local log file whenever the
size of the file reaches 500 kilobytes.

Select the JDK for the Domain

The JDK Selection pane prompts you to select the J2SE Development Kit (JDK) for the
startup mode you selected in the WebLogic Domain Startup Mode pane. The
Configuration Wizard presents a list of the JDKs supplied by BEA and installed with the
product, including:

 Sun JDK

From Sun Microsystems.

 BEA JRockit JDK

From BEA Systems, Inc.

You can choose one of the JDKs supplied by BEA or another JDK that you have installed
on your system. If you select a JDK supplied by BEA, the Configuration Wizard will
create server startup scripts that invoke the JDK you select.

Select only those JDKs that are supported on the platform you are using. For a list of the
JDKs that are supported for a specific platform, see Supported Configurations. The
default selection reflects the JDK that best meets the requirements of your environment,
based on the platform on which you are installing the domain.

Note: If you plan to use the JRockit JDK in production mode, BEA recommends that you
develop and test your applications using BEA JRockit early in your project cycle. For
information about BEA JRockit, see the BEA JRockit JDK documentation at the
following URL:

http://e-docs.bea.com/wljrockit/docs50/index.html

To select the JDK:

1. Perform one of the following steps:

• To use a JDK supplied by BEA, select BEA Supplied JDKs and then
select a JDK from the list.
• To use a JDK that is not installed with the product, select Other JDK,
click Browse, and navigate to the appropriate directory.

Note: The Configuration Wizard does not configure the start scripts to use
this type of JDK. You must change the start scripts manually.

2. Click Next to proceed to the next configuration window.

Related Topics

For information on changing the run-time mode after you have created a domain, see
"Change to production mode" in the WebLogic Server Administration Console Online
Help at http://e-
docs.bea.com/wls/docs90/ConsoleHelp/taskhelp/domainconfig/ChangeRuntimeModes.ht
ml.

Customize Environment and Services Settings

The Customize Environment and Services Settings window gives you the option to
change the distribution of your domain across servers, clusters, and machines, and to
modify existing JDBC and JMS file store settings.

If you choose not to customize any environment or services settings by accepting the
default (No), you proceed directly to creating the domain.

The following topics summarize the settings you can change.

Customize the Environment

You can customize the environment of your domain as follows:

 Change the configuration of the Administration Server, including listen address

and listen ports
 Add or delete Managed Servers, or change the configuration of existing Managed
Servers defined in the selected template
 Group the Managed Servers into clusters, which allows multiple Managed Servers
to operate as a single unit to host applications and resources. To group the
Managed Servers into clusters, you have the option of performing the following
steps:
• Add or delete clusters, or change the configuration of existing clusters
• Assign the Managed Servers to a cluster in the domain
• Create an HTTP proxy for each cluster within the domain
 Assign WebLogic Server instances to host machines. In a domain, machine
definitions identify a particular, physical piece of hardware and are used to
associate a computer with the Managed Servers it hosts. To map WebLogic
Server instances to host machines, you have the option of performing the
following steps:
• Add or delete machines, or change the configuration of existing machines
• Assign each instance of WebLogic Server to the machine on which it runs.

For more information, see Customizing the Environment.

Customize Existing JDBC and JMS Settings

If the domain source on which you are basing your domain contains a database
configuration, you have the option to do the following:

 Modify JDBC Data Source settings, including database type and drivers
 Test the connections to the database
 Load the database

If a JMS file store has been defined in the domain source, you can also change the file
store definition.

For more information, see Customizing Existing JDBC and JMS Settings.

Create the WebLogic Domain

The Create WebLogic Domain window prompts you to specify the name and pathname
for the domain, and initiate its creation.

To create the WebLogic domain:

1. Make sure that the Domain Name field contains the name of the required domain.
If you need to change the value in this field, click within the field and modify the
string displayed there.
 2. Make sure that the Domain Location field contains the name of the required
domain directory. If you need to change the value in this field:
1. Click Browse to invoke the Select a WebLogic Domain Directory dialog
box.
2. In the dialog box, navigate to the appropriate directory or manually enter
its pathname in the Location field. Click OK.

The domain directory can be located anywhere on your system. By default, it

resides in BEA_HOME\user_projects\domains\domain, where BEA_HOME is the
directory that contains the product installation, and domain is the name of the
domain directory defined by the selected domain template.

3. Click Create.

Note: You cannot overwrite an existing domain. If a domain with the name you
specify already exists in the selected location, you must either delete the existing
domain, or specify a different name or location for this domain.

The Creating Domain window is opened to display status messages during the
domain creation process.

The Configuration Wizard stores the config.xml file and all other generated
components in the domain directory that you specify.

Creating Domain
The Creating Domain window displays status messages during the domain creation
process. When the process is complete, the new domain is ready for use.

On this Perform the following task . . .

platform . . .
UNIX and Linux Click Done.
Windows Do one of the following:

 If you want to start the server immediately, select the Start

Admin Server check box and click Done.

 If you do not want to start the server at this time, click Done.

Configuring SSL
Configuring SSL is an optional step; however, BEA recommends using SSL in a
production environment. The following sections describe how to configure SSL for
WebLogic Server:

 SSL: An Introduction
 One-Way and Two-Way SSL
  Setting Up SSL: Main Steps
 Using Host Name Verification
 Enabling SSL Debugging
 SSL Session Behavior
 SSL Certificate Validation
 Using the nCipher JCE Provider with WebLogic Server
 Specifying the Version of the SSL Protocol

Notes: This chapter applies to WebLogic Server deployments using the security features
in this release of WebLogic Server as well as deployments using Compatibility Security.

All machines must be kept up to date with the current set of recommended patches from
the operating system vendors.

SSL: An Introduction

Secure Sockets Layer (SSL) provides secure connections by allowing two applications
connecting over a network connection to authenticate the other's identity and by
encrypting the data exchanged between the applications. Authentication allows a server
and optionally a client to verify the identity of the application on the other end of a
network connection. Encryption makes data transmitted over the network intelligible only
to the intended recipient.

SSL in WebLogic Server is an implementation of the SSL 3.0 and Transport Layer
Security (TLS) 1.0 specifications.

WebLogic Server supports SSL on a dedicated listen port which defaults to 7002. To
establish an SSL connection, a Web browser connects to WebLogic Server by supplying
the SSL listen port and the HTTPs protocol in the connection URL, for example,
https://myserver:7002.

Using SSL is computationally intensive and adds overhead to a connection. Avoid using
SSL in development environments when it is not necessary. However, always use SSL in
a production environment.

One-Way and Two-Way SSL

SSL can be configured one-way or two-way:

 With one-way SSL, the server is required to present a certificate to the client but
the client is not required to present a certificate to the server. To successfully
negotiate an SSL connection, the client must authenticate the server, but the
server will accept a connection from any client. One-way SSL is common on the
Internet where customers want to create secure connections before they share
personal data. Often, clients will also use SSL to log on in order for the server can
authenticate them.
 With two-way SSL, the server presents a certificate to the client and the client
presents a certificate to the server. WebLogic Server can be configured to require
clients to submit valid and trusted certificates before completing the SSL
connection.
Setting Up SSL: Main Steps

To set up SSL:

1. Obtain an identity (private key and digital certificates) and trust (certificates of
trusted certificate authorities) for WebLogic Server. Use the digital certificates,
private keys, and trusted CA certificates provided by the WebLogic Server kit, the
CertGen utility, Sun Microsystem's keytool utility, or a reputable vendor such as
Entrust or Verisign to perform this step.

2. Store the identity and trust. Private keys and trusted CA certificates which specify
identity and trust are stored in a keystore.

Note: This release of WebLogic Server supports private keys and trusted CA
certificates stored in files, or in the WebLogic Keystore provider for the purpose
of backward compatibility only.

3. Configure the identity and trust keystores for WebLogic Server in the WebLogic
Server Administration Console. See "Configure Keystores" in the Administration
Console Online Help.

4. Set SSL configuration options for the private key alias and password in the
WebLogic Server Administration Console. Optionally, set configuration options
that require the presentation of client certificates (for two-way SSL). See
"Configure SSL" and "Configure two-way SSL" in the Administration Console
Online Help.

Note: When starting a WebLogic Server instance, you can specify the command line
argument -Dweblogic.security.ssl.nojce=true to use a FIPS-compliant (FIPS 140-
2) crypto module.

For information on configuring identity and trust for WebLogic Server, see Obtaining
Private Keys, Digital Certificates, and Trusted Certificate Authorities and Storing Private
Keys, Digital Certificates, and Trusted Certificate Authorities.

Using Host Name Verification

A host name verifier ensures the host name in the URL to which the client connects
matches the host name in the digital certificate that the server sends back as part of the
SSL connection. A host name verifier is useful when an SSL client (or a WebLogic
Server acting as an SSL client) connects to an application server on a remote host. It
helps to prevent man-in-the-middle attacks.

By default, WebLogic Server has host name verification enabled. As a function of the
SSL handshake, WebLogic Server compares the common name in the SubjectDN in the
SSL server's digital certificate with the host name of the SSL server used to initiate the
SSL connection. If these names do not match, the SSL connection is dropped. The SSL
client is the actual party that drops the SSL connection if the names do not match.
If anything other than the default behavior is desired, either turn off host name
verification or configure a custom host name verifier. Turning off host name verification
leaves WebLogic Server vulnerable to man-in-the-middle attacks. BEA recommends
leaving host name verification on in production environments.

In this release of WebLogic Server, the host name verification feature is updated so that if
the host name in the certificate matches the local machine's host name, host name
verification passes if the URL specifies localhost, 127.0.01, or the default IP address
of the local machine.

For more information, see the following topics in the Administration Console Online
Help:

 "Verify Host Name Verification is enabled"

 "Disable Host Name Verification"
 "Configure a Custom Host Name Verifier"
 "Configuring SSL"

Enabling SSL Debugging

SSL debugging provides more detailed information about the SSL events that occurred
during an SSL handshake. The SSL debug trace displays information about:

 Trusted certificate authorities

 SSL server configuration information
 Server identity (private key and digital certificate)
 The encryption strength that is allowed by the license in use
 Enabled ciphers
 SSL records that were passed during the SSL handshake
 SSL failures detected by WebLogic Server (for example, trust and validity checks
and the default host name verifier)
 I/O related information

Use the following command-line properties to enable SSL debugging:

-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

The SSL debugging properties can be included in the start script of the SSL server, the
SSL client, and the Node Manager. For a Managed Server started by the Node Manager,
specify this command-line argument on the Remote Start page for the Managed Server.

SSL debugging dumps a stack trace whenever an ALERT is created in the SSL process.
The types and severity of the ALERTS are defined by the TLS specification.

The stack trace dumps information into the log file where the ALERT originated.
Therefore, when tracking an SSL problem, you may need to enable debugging on both
sides of the SSL connection (on both the SSL client or the SSL server). The log file
contains detailed information about where the failure occurred. To determine where the
ALERT occurred, confirm whether there is a trace message after the ALERT. An
ALERT received after the trace message indicates the failure occurred on the peer. To
determine the problem, you need to enable SSL debugging on the peer in the SSL
connection.

When tracking an SSL problem, review the information in the log file to ensure:

 The correct config.xml file was loaded

 The license (domestic or export) is correct
 The trusted certificate authority was valid and correct for this server.
 The host name check was successful
 The certificate validation was successful

Note: Sev 1 type 0 is a normal close ALERT, not a problem.

SSL Session Behavior

WebLogic Server allows SSL sessions to be cached. Those sessions live for the life of the
server.

Clients that use SSL sockets directly can control the SSL session cache behavior. The
SSL session cache is specific to each SSL context. All SSL sockets created by SSL
socket factory instances returned by a particular SSL context can share the SSL sessions.

Clients default to resuming sessions at the same IP address and port. Multiple SSL
sockets that use the same host and port share SSL sessions by default assuming the SSL
sockets are using the same underlying SSL context.

Clients that do not want to use SSL sessions must call

setEnableSessionCreation(false) on the SSL socket to ensure that no SSL sessions
are cached. This setting only controls whether an SSL session is added to the cache, it
does not stop an SSL socket from finding an SSL session that was already cached (for
example, SSL socket 1 caches the session, SSL socket 2 sets
setEnableSessionCreation to false but it can still reuse the SSL session from SSL
socket 1 since that session was put in the cache.)

SSL sessions exist for the lifetime of the SSL context; they are not controlled by the
lifetime of the SSL socket. Therefore, creating a new SSL socket and connecting to the
same host and port can resume a previous session as long as the SSL socket is created
using an SSL socket factory from the SSL context that has the SSL session in its cache.

By default, clients that use HTTPS URLs get a new SSL session for each URL because
each URL uses a different SSL context and therefore SSL sessions can not be shared or
reused. The SSL session can be retrieved using the weblogic.net.http.HttpsClient
class or the weblogic.net.http.HttpsURLConnection class. Clients can also resume
URLs by sharing a SSLSocket Factory between them.

Session caching is maintained by the SSL context, which can be shared by threads. A
single thread has access to the entire session cache, not just one SSL session, so multiple
SSL sessions can be used and shared in a single (or multiple) thread.

The following command-line arguments are ignored:

  weblogic.security.SSL.sessionCache.size
 weblogic.security.SSL.sessionCache.ttl

Configuring RMI over IIOP with SSL

Use SSL to protect Internet Interop-Orb-Protocol (IIOP) connections to Remote Method

Invocation (RMI) remote objects. SSL secures connections through authentication and
encrypts the data exchanged between objects.

To use SSL to protect RMI over IIOP connections, do the following:

1. Configure WebLogic Server to use SSL.

2. Configure the client Object Request Broker (ORB) to use SSL. Refer to the
product documentation for your client ORB for information about configuring
SSL.

3. Use the host2ior utility to print the WebLogic Server IOR to the console. The
host2ior utility prints two versions of the interoperable object reference (IOR),
one for SSL connections and one for non-SSL connections. The header of the IOR
specifies whether or not the IOR can be used for SSL connections.

4. Use the SSL IOR when obtaining the initial reference to the CosNaming service
that accesses the WebLogic Server JNDI tree.

For more information about using RMI over IIOP, see Programming WebLogic RMI.

SSL Certificate Validation

WebLogic Server ensures that each certificate in a certificate chain was issued by a
certificate authority. All X509 V3 CA certificates used with WebLogic Server must have
the Basic Constraint extension defined as CA, thus ensuring that all certificates in a
certificate chain were issued by a certificate authority. By default, any certificates for
certificate authorities not meeting this criteria are rejected. This section describes the
command-line argument that controls the level of certificate validation.

Note: If WebLogic Server is booted with a certificate chain that will not pass the
certificate validation, an information message is logged noting that clients could reject it.

Controlling the Level of Certificate Validation

By default WebLogic Server rejects any certificates in a certificate chain that do not have
the Basic Constraint extension defined as CA. However, you may be using certificates
that do not meet this requirement or you may want to increase the level of security to
conform to the IETF RFC 2459 standard. Use the following command-line argument to
control the level of certificate validation performed by WebLogic Server:

-Dweblogic.security.SSL.enforceConstraints=option

Table 11-1 describes the options for the command-line argument.

Table 11-1 Options for Description
-Dweblogic.security.SSL.enforceCon
straints

Option
strong or true Use this option to check that the Basic Constraints
extension on the CA certificate is defined as CA.

For example:

-
Dweblogic.security.SSL.enforceConstraints
=strong

or

-
Dweblogic.security.SSL.enforceConstraints
=true

By default, WebLogic Server performs this level of

certificate validation.
strict Use this option to check the Basic Constraints
extension on the CA certificate is defined as CA
and set to critical. This option enforces the IETF
RFC 2459 standard.

For example:

-
Dweblogic.security.SSL.enforceConstraints
=strict

This option is not the default because a number of

commercially available CA certificates do not
conform to the IETF RFC 2459 standard.
off Use this option to turn off checking for the Basic
Constraints extension. The rest of the certificate is
still validated.

CA certificates from most commercial certificate

authorities should work with the default strong
option.

For example:

-
Dweblogic.security.SSL.enforceConstraints
=off

BEA does not recommend using this option in a

 production environment. Instead, purchase new CA
certificates that comply with the IETF RFC 2459
standard.

Checking Certificate Chains

WebLogic Server provides a ValidateCertChain command-line utility to check whether

or not an existing certificate chain will be rejected by WebLogic Server. The utility uses
certificate chains from PEM files, PKCS-12 files, PKCS-12 keystores, and JKS
keystores. A complete certificate chain must be used with the utility. The following is the
syntax for the ValidateCertChain command-line utility:

java utils.ValidateCertChain -file pemcertificatefilename

java utils.ValidateCertChain -pem pemcertificatefilename
java utils.ValidateCertChain -pkcs12store pkcs12storefilename
java utils.ValidateCertChain -pkcs12file pkcs12filename password
java utils.ValidateCertChain -jks alias storefilename [storePass]

Example of valid certificate chain:

java utils.ValidateCertChain -pem zippychain.pem

Cert[0]: CN=zippy,OU=FOR TESTING

ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US

Cert[1]: CN=CertGenCAB,OU=FOR TESTING

ONLY,O=MyOrganization,L=MyTown,ST=MyState,C=US
Certificate chain appears valid

Example of invalid certificate chain:

java utils.ValidateCertChain -jks mykey mykeystore

Cert[0]: CN=corba1,OU=FOR TESTING ONLY,

O=MyOrganization,L=MyTown,ST=MyState,C=US
CA cert not marked with critical BasicConstraint indicating it is a CA
Cert[1]: CN=CACERT,OU=FOR TESTING ONLY,
O=MyOrganization,L=MyTown,ST=MyState,C=US

Certificate chain is invalid

Troubleshooting Problems with Certificate Validation

If SSL communications were working properly in a previous release of WebLogic Server

and start failing unexpectedly, the problem is mostly likely because the certificate chain
used by WebLogic Server is failing the validation.

Determine where the certificate chain is being rejected, and decide whether to update the
certificate chain with one that will be accepted or change the setting of the
-Dweblogic.security.SSL.enforceConstraints command-line argument.

To troubleshoot problems with certificates, use one of the following methods:

  If you know where the certificate chains for the processes using SSL
communication are located, use the ValidateCertChain command-line utility to
check whether the certificate chains will be accepted.
 Turn on SSL debug tracing on the processes using SSL communication. The
syntax for SSL debug tracing is:

-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

The following message indicates the SSL failure is due to problems in the
certificate chain:

<CA certificate rejected. The basic constraints for a CA

certificate were not marked for being a CA, or were not marked as
critical>

When using one-way SSL, look for this error in the client log. When using two-
way SSL, look for this error in the client and server logs.

Enabling SSL Debugging

SSL debugging provides more detailed information about the SSL events that occurred
during an SSL handshake. The SSL debug trace displays information about:

 Trusted certificate authorities

 SSL server configuration information
 Server identity (private key and digital certificate)
 The encryption strength that is allowed by the license in use
 Enabled ciphers
 SSL records that were passed during the SSL handshake
 SSL failures detected by WebLogic Server (for example, trust and validity checks
and the default host name verifier)
 I/O related information

Use the following command-line properties to enable SSL debugging:

-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true

The SSL debugging properties can be included in the start script of the SSL server, the
SSL client, and the Node Manager. For a Managed Server started by the Node Manager,
specify this command-line argument on the Remote Start page for the Managed Server.

SSL debugging dumps a stack trace whenever an ALERT is created in the SSL process.
The types and severity of the ALERTS are defined by the TLS specification.

The stack trace dumps information into the log file where the ALERT originated.
Therefore, when tracking an SSL problem, you may need to enable debugging on both
sides of the SSL connection (on both the SSL client or the SSL server). The log file
contains detailed information about where the failure occurred. To determine where the
ALERT occurred, confirm whether there is a trace message after the ALERT. An
ALERT received after the trace message indicates the failure occurred on the peer. To
determine the problem, you need to enable SSL debugging on the peer in the SSL
connection.
When tracking an SSL problem, review the information in the log file to ensure:

 The correct config.xml file was loaded

 The license (domestic or export) is correct
 The trusted certificate authority was valid and correct for this server.
 The host name check was successful
 The certificate validation was successful

Note: Sev 1 type 0 is a normal close ALERT, not a problem.

Using Certificate Lookup and Validation Providers

WebLogic Server SSL has built-in certificate validation, which given a set of trusted
CAs:

 Verifies that the last certificate in the chain is either a trusted CA or is issued by a
trusted CA.
 Completes the certificate chain with trusted CAs.
 Verifies the signatures in the chain.
 Ensures that the chain has not expired.

You can use certificate lookup and validation (CLV) providers to perform additional
validation on the certificate chain. In this release, WebLogic Server has added two CLV
providers:

 WebLogic CertPath Provider—Completes certificate paths and validates

certificates using the trusted CA configured for a particular server instance,
providing the same functionality as the built-in SSL certificate validation. This is
configured by default.
 Certificate Registry—The system administrator makes a list of trusted CA
certificates that are allowed access to the server; a certificate is valid if the end
certificate is in the registry. The administrator revokes a certificate by removing it
from the certificate registry providing an inexpensive mechanism for performing
revocation checking. This is not configured by default.

Alternatively, you can write a custom CertPathValidator to provide additional validation

on the certificate chain. For more information, see the Configuring WebLogic Security
Providers chapter.

Outbound SSL and two-way inbound SSL in a WebLogic Server instance receive
certificate chains during the SSL handshake that must be validated. An example of two-
way inbound SSL is a browser connecting to a Web application over HTTPS where the
browser sends the client's certificate chain to the Web application. The inbound
certificate validation setting is used for all two-way client certificate validation in the
server.

Examples of WebLogic Server using outbound SSL (that is, acting as an SSL client)
include:

 Connecting to the Node Manager

 Connecting to another WebLogic Server over the administration port
  Connecting to an external LDAP server, such as the LDAPAuthenticator

Using the Administration Console or WLST, you can independently configure inbound
and outbound SSL certificate validation using these SSLMBean attributes:
InboundCertificateValidation and OutboundCertificateValidation.

Legal values for both attributes are:

 BUILTIN_SSL_VALIDATION: Use the built-in SSL certificate validation code to

complete and validate the certificate chain. That is, configure SSL to work as has
in previous releases. This is the default behavior.
 BUILTIN_SSL_VALIDATION_AND_CERT_PATH_VALIDATORS: Use the built-in
trusted CA-based validation and the configured CertPathValidator providers to
perform additional validation. That is, configure SSL to work as has in previous
releases plus do extra validation.

For more information, see:

 SSLMBean in the WebLogic Server MBean Reference

 "Set Up SSL" in the Administration Console Online Help

Using the nCipher JCE Provider with WebLogic Server

Note: Java Cryptography Extension (JCE) providers are written using the application
programming interfaces (APIs) in the JCE available in JDK 5.0. This type of provider is
different from the providers written using the WebLogic Security Service Provider
Interfaces (SSPIs). WebLogic Server does not provide a JCE provider by default.

SSL is a key component in the protection of resources available in Web servers.

However, heavy SSL traffic can cause bottlenecks that impact the performance of Web
servers. JCE providers like nCipher which use a hardware card for encryption, offload
SSL processing from Web servers freeing the servers to process more transactions. They
also provide strong encryption and cryptographic processes to preserve the integrity and
secrecy of keys.

WebLogic Server supports the use of the following JCE providers:

 The JDK JCE provider (SunJCE) in the JDK 5.0. For more information about the
features in the JDK JCE provider, see http://java.sun.com/products/jce/.

By default, the JCE provider in the JDK 5.0 has export strength jurisdiction policy
files. After filling out the appropriate forms, the domestic strength jurisdiction
policy files are downloadable from Sun Microsystems at
http://java.sun.com/products/jce/javase.html#UnlimitedDownload.

The BEA license will continue to control the strength of the cryptography used by
the WebLogic Server Application Programming Interfaces (APIs). Client code
without the appropriate domestic strength cryptography license will only be able
to use the J2SE export strength default cryptography. On the server, there will
always be a BEA license that will enable either export or domestic strength
cryptography.
  The nCipher JCE provider. For more information about the nCipher JCE provider,
see http://www.ncipher.com/solutions/sslsecurity.html.

To install the nCipher JCE provider:

1. Install and configure the hardware for the nCipher JCE provider per the product's
documentation.

2. Install the files for the nCipher JCE provider. The following files are required:
• Jurisdiction policy files—The JDK installs these files by default but they
are of limited export strength.
• Certificate that signed the JAR file

Note: This step may have been performed as part of installing the
hardware for nCipher JCE provider. In that case, verify that the files are
correctly installed.

• The JCE provider JAR files

The files are installed in one of the following ways:

• As an installed extension. Copy the files to one of the following locations:

JAVA_HOME/jre/lib/ext

For example:

BEA_HOME/jdk150_03/jre/lib/ext

• In the CLASSPATH of the server.

3. Edit the Java security properties file (java.security) to add the nCipher JCE
provider to the list of approved JCE providers for WebLogic Server. The Java
security properties file is located in:

JAVA_HOME/jre/lib/security/java.security

Specify the nCipher JCE provider as:

security.provider.n=com.ncipher.provider.km.mCipherKM

where

n specifies the preference order that determines the order in which providers are
searched for requested algorithms when no specific provider is requested. The
order is 1-based; 1 is the most preferred, followed by 2, and so on.

The nCipher JCE provider must follow the RSA JCA provider in the security
properties file. For example:

security.provider.1=sun.security.provider.Sun
 security.provider.2=com.sun.rsajca.Provider

security.provider.3=com.ncipher.provider.km.mCipherKM

4. Boot WebLogic Server.

5. To ensure the nCipher JCE provider is working properly, enable debugging

according to the nCipher product documentation.

Specifying the Version of the SSL Protocol

WebLogic Server supports both the SSL V3.0 and TLS V1.0 protocols. When WebLogic
Server is acting as an SSL server, it will agree to use whichever of these protocols the
client specifies as preferred in its client hello message. When WebLogic Server is acting
as an SSL client, it will specify TLS1.0 as the preferred protocol in its SSL V2.0 client
hello message, but will agree to SSL V3.0 as well, if that is the highest version that the
SSL server on the other end supports. The peer must respond with an SSL V3.0 or TLS
V1.0 message or the SSL connection is dropped.

While in most cases the SSL V3.0 protocol is acceptable there are circumstances
(compatibility, SSL performance, and environments with maximum security
requirements) where the TLS V1.0 protocol is desired. The
weblogic.security.SSL.protocolVersion command-line argument lets you specify
which protocol is used for SSL connections.

Note: The SSL V3.0 and TLS V1.0 protocols can not be interchanged. Only use the TLS
V1.0 protocol if you are certain all desired SSL clients are capable of using the protocol.

The following command-line argument can be specified so that WebLogic Server

supports only SSL V3.0 or TLS V1.0 connections:

 -Dweblogic.security.SSL.protocolVersion=SSL3—Only SSL V3.0

messages are sent and accepted.
 -Dweblogic.security.SSL.protocolVersion=TLS1—Only TLS V1.0
messages are sent and accepted.
 -Dweblogic.security.SSL.protocolVersion=ALL—This is the default
behavior.

Keytool
From ConchShell

Jump to: navigation, search[edit]

How to use Keytool - notes from my own experiences

Mark Foster 5/15/2003

Say you want to obtain a server certificate from Verisign. You will need to create a
keystore with a private key, then create a certificate signing request to give them. They
will give you a CA-signed certificate in return.

Create your key (this also creates the keystore if it doesn't exist). Make sure to use the
full state spelling and cn of your web site.

keytool -v -genkey -keyalg RSA -keystore keystore -dname

"cn=www.example.com, ou=None, L=Seattle, ST=Washington, o=ExampleOrg,
c=US"

Generate the CSR. Be sure and specify sigalg here or it won't work

keytool -certreq -sigalg MD5withRSA -file www.example.com.csr

-keystore keystore -storepass password

Now go to http://digitalid.verisign.com/

Click on SSL Certificates

Click on Buy SSL

Choose from Secure Site (40-bit) or Secure Site Pro (128-bit).

I highly recommend two-years as it will save you the hassle-factor! When it asks for your
vendor, just choose BEA WebLogic, as Javasoft has recently been removed. This choice
is probably less important than you might think -- when I asked Verisign customer
service I was told this is more of a survey than anything else.

Verisign will email you the signed certificate as an attachment. Save the attachment as
www.example.com.crt, then import it into the keystore

keytool -import -keystore keystore -keyalg RSA -import -trustcacerts

-file www.example.com.crt

That should do it!

If you chose to get a Global Server ID (128-bit) you will need to import the intermediate
CA certificate.

You'll know this is the case if you receive this error when you try to install the certificate
that Verisign emailed to you.

keytool error: java.lang.Exception: Failed to establish chain from

reply

The intermediate CA certificate can be found here:

https://www.verisign.com/support/install/intermediate.html

Save it as verisign_inter.cer, then do

keytool -keystore keystore -keyalg RSA -import -trustcacerts -alias

cacert -file verisign_inter.cer
 Certificate was added to keystore

Now go back and try importing your signed certificate again.

[edit]

References

Sun's J2EETM Tutorial Setting up a Server Certificate

• http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/Security10.html

Keytool Documentation from Sun

• http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html

Using Java's Keytool

• http://www.churchillobjects.com/c/11201e.html

Secure Sockets with JSSE & OpenSSL

• http://www.churchillobjects.com/c/11201g.html

[edit]

See Also

HowTo compare two cacerts (UNIX)

• http://www.techie-blogs.com/wordpress/web/support/security/howto-compare-
two-cacerts-unix/

OpenSSL to Keytool Conversion Tips

• http://mark.foster.cc/kb/openssl-keytool.html

Keytool cacert extraction to PEM format using OpenSSL and keytool

• http://mark.foster.cc/kb/cacert-keystore-extraction.html

How to obtain an SSL certificate for your server (but using openssl)

• http://www.credentia.cc/certs/howto/obtain.html
Production-time Redeployment of Applications in WebLogic Server 9.0

Abstract

Upgrading a running application in a J2EE production environment isn't easy. You either
have to undeploy the old version of the application and deploy the new one—causing a
temporary outage—or you may have to set up a redundant server/cluster to route the new
requests.

BEA WebLogic Server 9.0 supports a production redeployment feature that provides a
way to seamlessly upgrade an application in a production environment without affecting
application availability. After redeploying a new version of the application, all new client
connection requests go to the new application. The existing client connections continue to
use the old application that will be undeployed/retired after all the existing connections
are closed. The two application versions are completely isolated from each other and do
not share any resources. Alternatively, the old version of the application can be retired by
specifying a retire timeout for the application.

This article uses a sample application to demonstrate this functionality.

Requirements

Currently, WebLogic Server 9.0 supports this production redeployment feature only for
Web application (WAR) modules and enterprise applications (EARs). All other types of
archives (EJB JAR, JCA RAR, WebServices archives, JMS, or JDBC standalone
modules) are not supported. EARs can contain all supported module types, except
WebServices archives. Production redeployment only supports HTTP clients; Java clients
are not supported. Attempting to perform production redeployment with an unsupported
archive type will result in an error. To redeploy such modules, remove their version
identifiers and explicitly redeploy the modules.

In addition, only versioned applications can be redeployed using this feature. A versioned
application is an application that has an application archive version specified in the
manifest of the application archive.

A deployed application must specify a version number before you can perform
subsequent production redeployment operations on the application. In other words, you
cannot deploy a non-versioned application and later perform production redeployment
with a new version of the application.

WebLogic Server 9.0 can host a maximum of two different versions of an application at
any one time. Also, when you redeploy a new version of an application, you cannot
change the application's deployment targets, security model, or persistent store settings.
To change any of the above features, you must first undeploy the active version of the
application.

Application Version Information

The application version information can be specified in the MANIFEST.MF file's

WebLogic-Application-Version property. The manifest is a special file that can
contain information about the files packaged in a JAR file. By tailoring this "meta"
information that the manifest contains, you enable the JAR file to serve a variety of
purposes.

For example, an application archive whose application archive version is "v1" could have
the following manifest content:

Manifest-Version: 1.0

Created-By: 1.4.1_05-b01 (Sun Microsystems Inc.)

WebLogic-Application-Version: v1

The application archive version is a string that can only contain the following characters:
alphanumeric ("A"-"Z," "a"-"z," "0"-"9"), period ("."), underscore ("_"), and hyphen
("-"). The length of the application archive version should be less than 215 characters.
Additionally, the application archive version string cannot be "." or "..". You can either
specify a version for an application using the manifest file, or assign one when using the
Deployer tool's -appversion option. The value specified in MANIFEST.MF file will
take precedence over the -appversion value.

The version number is important when considering the redeployment of versionable

applications. If a new application archive version is specified, WebLogic Server will
perform production redeployment with version isolation. If the same application archive
version is specified, WebLogic Server will perform in-place redeployment.

The Sample Versioned Application

The attached sample application (VersionedApp1) contains a Web application, which has
three JSP files:

• The versionedjsp.jsp file contains a simple print statement.

• The invalidatesession.jsp contains a session.invalidate() command to
invalidate all the sessions.
• The timeoutsession.jsp file contains code to set the timeout value for the
session.

The other application, VersionedApp2, contains the same set of files, but the
versionedjsp.jsp file will print a different message.

We'll use these applications to demonstrate the versioning process.

Deploying the Application

The sample applications provided along with this article do not have version information
in their manifest files. If you want to use production redeployment with an application
that does not include a version string in the manifest file, the Deployer tool allows you to
manually specify a unique version string using the -appversion option when deploying
or redeploying an application. Run this command to deploy the application with a version
of version1:

java weblogic.Deployer -adminurl http://localhost:8802

-username weblogic -password weblogic -name VersionedApp
-targets adminServer
-deploy -source C:/tmp/VersionedApp1 -appversion version1

Deployer is a Java-based deployment tool that provides a command-line interface to the

WebLogic Server deployment API. Deployer is intended for administrators and
developers who want to perform interactive, command line-based deployment operations.

Note that the version string specified with -appversion is applied only when the
deployment source files do not specify a version string in MANIFEST.MF. For
applications with version information in the manifest files, you need not provide the
-appversion option.

You can also display version information for deployed applications from the command
line using the Deployer -listapps command. So for example, after deploying the above
application you can run this command to list the application:

java weblogic.Deployer -adminurl http://localhost:8802

-user weblogic -password weblogic -listapps

Redeploying a New Version of the Application

Now that we've deployed the application, let's look at redeploying it. Since our
deployment files do not contain version information in the manifest files, we perform
redeploy with the -appversion option as mentioned above:

java weblogic.Deployer -adminurl http://localhost:8802

-username weblogic -password weblogic -name VersionedApp
-targets adminServer -redeploy -source
C:/tmp/VersionedApp2 -appversion version2

If you want to specify a fixed time period after which the older version of the application
is undeployed (regardless of whether clients finish their work), use the -retiretimeout
option with the -redeploy command. (-retiretimeout specifies the number of seconds
after which the older version of the application is retired):

java weblogic.Deployer -adminurl http://localhost:8802

-username weblogic -password weblogic -name VersionedApp
-targets adminServer -redeploy -source
C:/tmp/VersionedApp2 -appversion version2 -retiretimeout 300

If WebLogic Server has not yet retired an application version, you can immediately
undeploy the application version without waiting for retirement to complete. This may be
necessary if, for example, an application remains in the retiring state with only one or two
long-running client sessions that you do not want to preserve. To force the undeployment
of a retiring version of an application, use the -undeploy command and specify the
application version:

java weblogic.Deployer -adminurl http://localhost:8802

 -username weblogic -password weblogic -name VersionedApp
-targets adminServer -undeploy -name VersionedApp
-appversion version1

If you do not explicitly specify an application version with the -appversion option,
WebLogic Server undeploys the active version and all retired versions of the application.

Verifying the Deployment

After deploying the first version of the application, open a browser and invoke the
versionedjsp.jsp:

http://localhost:8802/VersionedApp/versionedjsp.jsp

That should establish an HTTP session to the VersionedApp1 application. In the browser
window we should see the "Output from VersionedApp1 JSP" message. After deploying
the VersionedApp2 application, open another browser window and invoke the
versionedjsp.jsp. Now we should see the "Output from VersionedApp2 JSP" message
from the VersionedApp2 application. At this time, both the versions of application should
be alive.

Now invoke the invalidatesession.jsp from the first browser window:

http://localhost:8802/VersionedApp/invalidatesession.jsp

This will invalidate all the established sessions to the VersionedApp1 application. Take a
look at the server console window. The retirement process should have started now. Wait
a few moments for the retirement process to complete and invoke versionedjsp.jsp
from the first browser window:

http://localhost:8802/VersionedApp/versionedjsp.jsp

This time you should see the "Output from VersionedApp2 JSP" message from the
VersionedApp2 application.

Rolling Back the Production Redeployment Process

Reversing the production redeployment process switches the state of the active and
retiring applications and redirects new client connection requests accordingly. Reverting
the production redeployment process may be necessary if you detect a problem with a
newly deployed version of an application, and you want to stop clients from accessing it.

To roll back the production redeployment process, issue a second -redeploy command
and specify the deployment source files for the older version:

java weblogic.Deployer -adminurl http://localhost:8802

-user weblogic -password weblogic -redeploy
-name VersionedApp C:/tmp/VersionedApp1
-retiretimeout 300
Conclusion

Production redeployment is a very powerful functionality. With this functionality,

customers get the ability to roll out application upgrades in a production environment
transparently, without disruption to clients. Production redeployment not only requires
fewer hardware resources but also provides more flexibility and control of application
availability. Administrators should definitely consider using this functionality in
production environments, which will not only make their tasks easier, but also provide
minimal disruption to the end user.

Downloads

• VersionedApp1.zip - version 1 sample application

• VersionedApp2.zip - version 2 sample application

References:

Developing Applications for Production Redeployment (product

documentation)

• weblogic.Deployer Command-Line Reference (product documentation)

• What's New in WebLogic Server 9.0 (product documentation)
• Working with manifest files (Sun Microsystems documentation)
• dev2dev BEA WebLogic Server Product Center

Abhijit Patil works as a Senior Software Engineer at BEA Systems. His expertise includes
WebLogic application clustering and deployment.

Seetharam Param works as a Senior Software Engineer at BEA Systems. His expertise
includes application deployment in WebLogic Server.

Installing and Configuring the Apache HTTP Server Plug-In

The following sections describe how to install and configure the Apache HTTP Server
Plug-In:

 Overview of the Apache HTTP Server Plug-In

 Certifications
 Installing the Apache HTTP Server Plug-In
 Configuring the Apache HTTP Server Plug-In
 Template for the Apache HTTP Server httpd.conf File
 Sample httpd.conf Configuration Files
 Using SSL with the Apache Plug-In
 Issues with SSL-Apache Configuration
 Connection Errors and Clustering Failover
 Overview of the Apache HTTP Server Plug-In

The Apache HTTP Server Plug-In allows requests to be proxied from an Apache HTTP
Server to WebLogic Server. The plug-in enhances an Apache installation by allowing
WebLogic Server to handle those requests that require the dynamic functionality of
WebLogic Server.

The plug-in is intended for use in an environment where an Apache Server serves static
pages, and another part of the document tree (dynamic pages best generated by HTTP
Servlets or JavaServer Pages) is delegated to WebLogic Server, which may be operating
in a different process, possibly on a different host. To the end user—the browser—the
HTTP requests delegated to WebLogic Server still appear to be coming from the same
source.

HTTP-tunneling, a technique which allows HTTP requests and responses access through
a company's firewall, can also operate through the plug-in, providing non-browser clients
access to WebLogic Server services.

The Apache HTTP Server Plug-In operates as an Apache module within an Apache
HTTP Server. An Apache module is loaded by Apache Server at startup, and then certain
HTTP requests are delegated to it. Apache modules are similar to HTTP servlets, except
that an Apache module is written in code native to the platform.

Limitations in Apache Version 1.3.x

Version 1.3x of the Apache HTTP Server has several limitations with the WebLogic
Server plug-in that do not exist in later versions.

Keep-Alive Connections Not Supported

Version 1.3.x of the Apache HTTP Server Plug-In creates a socket for each request and
closes the socket after reading the response. Because Apache HTTP Server is
multiprocessed, connection pooling and keep-alive connections between WebLogic
Server and the Apache HTTP Server Plug-In cannot be supported.

Inconsistent States

The Apache HTTP Server has a multi-process architecture, and the state of the plug-in
cannot be synchronized across multiple child processes. The following types of problems
may occur:

 In a clustered environment, a plug-in may dispatch requests to an

unavailable WebLogic Server instance because the DynamicServerList is
not current in all plug-in processes.
 In non-clustered environment, a plug-in may lose the stickiness of a
session created after restarting WebLogic Server instances, because some
plug-in processes do not have the new JVMID of those restarted servers,
and treat them as unknown JVMIDs.
To temporarily correct inconsistencies of this type, restart or send a HUP signal (kill
-HUP) to the Apache server to refresh all plug-in processes.

To avoid these issues, upgrade to Apache 2.0.x, and configure Apache to use the multi-
threaded and single-process model by setting MaxSpareServers=1 in
httpd.conf. For information about editing httpd.conf, see Configuring the
Apache HTTP Server Plug-In.

Keep-Alive Connections in Apache Version 2.0

Version 2.0 of the Apache HTTP Server Plug-In improves performance by using a
reusable pool of connections from the plug-in to WebLogic Server. The plug-in
implements HTTP 1.1 keep-alive connections between the plug-in and WebLogic Server
by reusing the same connection in the pool for subsequent requests from the same client.
If the connection is inactive for more than 30 seconds, (or a user-defined amount of time)
the connection is closed and returned to the pool. You can disable this feature if desired.
For more information, see "KeepAliveEnabled".

Proxying Requests

The plug-in proxies requests to WebLogic Server based on a configuration that you
specify. You can proxy requests based on the URL of the request (or a portion of the
URL). This is called proxying by path. You can also proxy requests based on the MIME
type of the requested file. Or you can use a combination of both methods. If a request
matches both criteria, the request is proxied by path. You can also specify additional
parameters for each type of request that define additional behavior of the plug-in. For
more information, see Configuring the Apache HTTP Server Plug-In.

Certifications

The Apache HTTP Server Plug-In is supported on Linux, Solaris, AIX, Windows, and
HPUX11 platforms. Plug-ins are not supported on all operating systems for all
releases.For information on platform support for specific versions of Apache, see
Platform Support for WebLogic Server Plug-ins and Web Servers in Supported
Configurations for WebLogic Server 7.0.

Installing the Apache HTTP Server Plug-In

You install the Apache HTTP Server Plug-In as an Apache module in your Apache
HTTP Server installation. The module is installed either as a Dynamic Shared Object
(DSO) or as a statically linked module. (Installation as a statically linked module is only
available for Apache version 1.3.x). There are separate instructions in this section for
DSO and statically linked module installation.

Installing the Apache HTTP Server Plug-In as a Dynamic Shared

Object

To install the Apache HTTP Server Plug-In as a dynamic shared object:

1. Locate the shared object file for your platform.

The Apache plug-in is distributed as a shared object (.so) for use on Solaris,
Linux, Windows, AIX and HPUX11 platforms. Each shared object file is
distributed as a separate version, depending on the platform, whether or not
SSL is to be used between the client and Apache, and the encryption strength
for SSL (regular or 128 bit— 128 bit versions are only installed if you install
the 128 bit version of WebLogic Server). The shared object files are located in
the following directories of your WebLogic Server installation (where
WL_HOME is the top-level installation directory for the WebLogic platform
and the Server directory contains WebLogic Server installation files):

Shared Object Location

Table 2-1 Locations
of Plug-In Shared
Object Files

Operating System
Solaris WL_HOME/server/lib/solaris
Linux WL_HOME/server/lib/linux/i686

WL_HOME/server/lib/linux/s390
Windows WL_HOME\server\bin\mod_wl_20.so
(applicable to Apache versions 2.0.x )

WL_HOME\server\bin
HPUX11 WL_HOME/server/lib/hpux11
AIX WL_HOME/server/lib/aix

Warning: If you are running Apache 2.0.x server on HP-UX11, set the
environment variables specified below before you build the Apache server.
Because of a problem with the order in which linked libraries are loaded on
HP-UX, a core dump can result if the load order is not preset as an
environment variable before building. Set the following environment
variables:

export EXTRA_LDFLAGS="-lstd -lstream -lCsup -lm -lcl -ldld

-lpthread"
Proceed with the configure, make, and make install steps:
./configure --prefix=$INSTALLATION_DIRECTORY --enable-so --with-
mpm=worker
make
make install
See the Apache HTTP Server documentation for more information about
building and configuring your Apache server.

Choose the appropriate shared object from the following table:

Apache Version Regular Strength 128-bit
Encryption Encryption
Standard Apache mod_wl.so mod_wl128.so
Version 1.x
Apache w/ mod_wl_ssl.so mod_wl128_ssl.so
SSL/EAPI
Version 1.x

(Stronghold,
modssl etc.)
Apache + Raven mod_wl_ssl_raven.so mod_wl128_ssl_raven.so
Version 1.x

Required because
Raven applies
frontpage patches
that makes the
plug-in
incompatible with
the standard shared
object
Standard Apache mod_wl_20.so mod_wl28_20.so
Version 2.0.x

2. Enable the shared object.

The Apache HTTP Server Plug-In will be installed in your Apache HTTP
Server installation as an Apache Dynamic Shared Object (DSO). DSO
support in Apache is based on a module named mod_so.c that must be
enabled before mod_wl.so is loaded. If you installed Apache using the
supplied script, mod_so.c should already be enabled. To verify that
mod_so.c is enabled, execute one of the following commands:

For Apache 1.x, APACHE_HOME\bin\httpd -l

For Apache 2.0.x, APACHE_HOME\bin\Apache -l

(Where APACHE_HOME is the directory containing your Apache HTTP

Server installation.)

This command lists all of the enabled modules. If mod_so.c is not

listed, build your Apache HTTP Server from the source code, making sure
that the following options are configured:

...
--enable-module=so
--enable-rule=SHARED_CORE
...
3. Install the Apache HTTP Server Plug-In in the Apache 1.x server with
a support program called apxs (APache eXtenSion, see Manual Page: apxs at
http://httpd.apache.org/docs/programs/apxs.html). Issue the following
command :

$ apxs mod_so.c

to build Dynamic Shared Object-based modules outside of the Apache

source tree and add the following line to the httpd.conf file:

AddModule mod_so.c

For Apache 2.0.x, copy the mod_wl_20.so file to the

APACHE_HOME\modules directory rather than running apxs. For more
information, see the Apache HTTP Server Version 2.0 documentation.

4. Activate the weblogic_module, the WebLogic Server extension to

the Apache server:
• For Apache 1.x, in your WebLogic Server installation, use a
command shell to navigate to the directory that contains the shared
object for your platform and activate the weblogic_module by
issuing this command (note that you must have Perl installed to run
this Perl script):

perl APACHE_HOME\bin\apxs -i -a -n weblogic mod_wl.so

This command copies the mod_wl.so file to the

APACHE_HOME\libexec directory. It also adds two lines of
instructions for weblogic_module to the httpd.conf file
and activates the module. Make sure that the following lines were
added to your APACHE_HOME/conf/httpd.conf file in your
Apache 1.x server installation:

LoadModule weblogic_module libexec/mod_wl.so

AddModule mod_weblogic.c

• For Apache 2.0.x, add the following line to your

APACHE_HOME/conf/httpd.conf file manually:

LoadModule weblogic_module modules/mod_wl_20.so

5. Configure any additional parameters in the Apache httpd.conf

configuration file as described in the section Configuring the Apache HTTP
Server Plug-In. The httpd.conf file allows you to customize the behavior of
the Apache HTTP Server Plug-In.

6. Verify the syntax of the APACHE_HOME\conf\httpd.conf file with one of

the following commands:

For Apache 1.x, APACHE_HOME\bin\apachect1 configtest

For Apache 2.0.x, APACHE_HOME\bin\Apache -t
 The output of this command indicates any errors in your httpd.conf
file.

Note: Apache -t is a valid command for Apache 2.0.x on Windows. However, for Apache
2.0.x on HP-UX, Apache -t is not a valid command, because Apache 2.0.x on HP-UX has
apachectl and not the Apache command file.

7. Restart Weblogic Server.

8. Start (or restart if you have changed the configuration) Apache HTTP
Server.

9. Test the Apache plug-in by opening a browser and setting the URL to
the Apache Server + "/weblogic/", which should bring up the default
WebLogic Server HTML page, welcome file, or default servlet, as defined for
the default Web Application on WebLogic Server. For example:

http://myApacheserver.com/weblogic/

Installing the Apache HTTP Server Plug-In as a Statically Linked

Module

To install the Apache HTTP Server Plug-In as a statically linked module:

1. Locate the linked library file for your platform.

Each library file is distributed as a separate version, depending on the

platform and the encryption strength for SSL (regular or 128-bit—128-bit
versions are only installed if you install the 128-bit version of WebLogic
Server). The library files are located in the following directories of your
WebLogic Server installation:

Solaris
WL_HOME/Server/lib/solaris
Linux
WL_HOME/Server/lib/linux
HPUX11
WL_HOME/Server/lib/hpux11

Choose the appropriate shared object from the following table.

Apache Version Regular Strength 128-bit

Encryption Encryption
Standard Apache Version libweblogic.a libweblogic128.a
1.3.x

If you are using the Gnu C Compiler (gcc), gcc 2.95.x is the required version.

2. Unpack the Apache Plug-In distribution using the following

command:
 tar -xvf apache_1.3.x.tar

3. Within the unpacked distribution switch to the src/modules

directory.

4. Create a directory called weblogic.

5. Copy Makefile.libdir, Makefile.tmpl from the lib directory of

your WebLogic Server installation to src\modules\weblogic.

6. Copy libweblogic.a (use libweblogic128.a instead, if you are

using 128 bit security.) from the same directory containing the linked library
file (see step 1. ) to src\modules\weblogic.

7. If you are using regular strength encryption, execute the following

command from the Apache 1.3 home directory:

configure --activate-module=src\modules\weblogic\libweblogic.a

8. If you are using 128 bit encryption, execute the following command
(on a single line) from the Apache 1.3 home directory:

configure--activate-module=
src\modules\weblogic\libweblogic128.a

9. Execute the following command:

make

10. Execute the following command:

make install

11. Follow steps 4 through 8, inInstalling the Apache HTTP Server Plug-
In as a Dynamic Shared Object

Configuring the Apache HTTP Server Plug-In

After you install the plug-in in the Apache HTTP server, edit the httpd.conf file to
configure the Apache plug-in. Editing the httpd.conf file informs the Apache Web
server that it should load the native library for the plug-in as an Apache module and also
describes which requests should be handled by the module.

Editing the httpd.conf File

Edit the httpd.conf file in your Apache HTTP server installation to configure the
Apache HTTP Server Plug-In:

1. Open the httpd.conf file. The file is located at

APACHE_HOME\conf\httpd.conf (where APACHE_HOME is the root directory
of your Apache HTTP server installation).
2. For Apache 1.x, verify that the following two lines were added to the
httpd.conf file when you ran the apxs utility:

LoadModule weblogic_module libexec\mod_wl.so

AddModule mod_weblogic.c

3. For Apache 2.0.x, add the following line to the httpd.conf file:

LoadModule weblogic_module modules\mod_wl_20.so

4. Add an IfModule block that defines one of the following:

For a non-clustered WebLogic Server:

The WebLogicHost and WebLogicPort parameters.

For a cluster of WebLogic Servers:

The WebLogicCluster parameter.

For example:

<IfModule mod_weblogic.c>
WebLogicHost myweblogic.server.com
WebLogicPort 7001
</IfModule>

5. If you want to proxy requests by MIME type, also add a

MatchExpression line to the IfModule block. (You can proxy requests by
path in addition to or instead of proxying by MIME type. Proxying by path
takes precedence over proxying by MIME type. To configure proxying
requests by path, see step 6. )

For example, the following IfModule block for a non-clustered

WebLogic Server specifies that all files with MIME type .jsp are
proxied:

<IfModule mod_weblogic.c>
WebLogicHost myweblogic.server.com
WebLogicPort 7001
MatchExpression *.jsp
</IfModule>

You can also use multiple MatchExpressions, for example:

<IfModule mod_weblogic.c>
WebLogicHost myweblogic.server.com
WebLogicPort 7001
MatchExpression *.jsp
MatchExpression *.xyz
</IfModule>

If you are proxying requests by MIME type to a cluster of WebLogic

Servers, use the WebLogicCluster parameter instead of the
WebLogicHost and WebLogicPort parameters. For example:
 <IfModule mod_weblogic.c>
WebLogicCluster w1s1.com:7001,w1s2.com:7001,w1s3.com:7001
MatchExpression *.jsp
MatchExpression *.xyz
</IfModule>

6. If you want to proxy requests by path, use the Location block and
the SetHandler statement. SetHandler specifies the handler for the Apache
HTTP Server Plug-In module. For example the following Location block
proxies all requests containing /weblogic in the URL:

<Location /weblogic>
SetHandler weblogic-handler
</Location>

7. Define any additional parameters for the Apache HTTP Server Plug-
In.

The Apache HTTP Server Plug-In recognizes the parameters listed in

General Parameters for Web Server Plug-Ins. To modify the behavior of
your Apache HTTP Server Plug-In, define these parameters either:

• In a Location block, for parameters that apply to proxying by

path, or
• In an IfModule block, for parameters that apply to proxying by
MIME type.

Alternative Procedure for Editing the httpd.conf File

 As an alternative to the procedure in Editing the httpd.conf File you
can define parameters in a separate file called weblogic.conf file that is
included in the IfModule block. Using this included file may help modularize
your configuration. For example:

<IfModule mod_weblogic.c>
# Config file for WebLogic Server that defines the parameters
Include conf/weblogic.conf
</IfModule>

Note: Defining parameters in an included file is not supported when using

SSL between Apache HTTP Server Plug-In and WebLogic Server.

 Enter each parameter on a new line. Do not put an `=' between the
parameter and its value. For example:

PARAM_1 value1
PARAM_2 value2
PARAM_3 value3

 If a request matches both a MIME type specified in a

MatchExpression in an IfModule block and a path specified in a Location
block, the behavior specified by the Location block takes precedence.
 If you define the CookieName parameter, you must define it in an
IfModule block.
  If you use the <files> block in addition to the <location> block to
match requests and you are using Stronghold SSL (a commercial Apache-
based Web server) with virtual hosting, MatchExpression is ignored and the
rules defined in the <files> and <location> blocks are applied to the
request. If you are not using Stronghold, rules in the <location> block
overrule those in a <files> block.
 If you use the <VirtualHost> block, you must place all the
configuration parameters (MatchExpression, for example) for each virtual
host within its <VirtualHost> block.
 If you want to have only one log file for all the virtual hosts
configured in your environment, you can achieve it using global properties.
Instead of specifying the same Debug, WLLogFile and WLTempDir properties
in each virtual host you can specify them just once in the <IfModule> tag
 Sample httpd.conf file:

<IfModule mod_weblogic.c>
WebLogicCluster agarwalp02:8005,agarwalp02:8006
Debug ON
WLLogFile c:/tmp/global_proxy.log
WLTempDir "c:/myTemp"
DebugConfigInfo On
KeepAliveEnabled ON
KeepAliveSecs 15
</IfModule>
<Location /jurl>
SetHandler weblogic-handler
WebLogicCluster agarwalp01:7001
</Location>
<Location /web>
SetHandler weblogic-handler
PathTrim /web
Debug OFF
WLLogFile c:/tmp/web_log.log
</Location>
<Location /foo>
SetHandler weblogic-handler
PathTrim /foo
Debug ERR
WLLogFile c:/tmp/foo_proxy.log
</Location>

All the requests which match /jurl/* will have Debug Level set to ALL and log messages
will be logged to c:/tmp/global_proxy.log file. All the requests which match /web/* will
have Debug Level set to OFF and no log messages will be logged. All the requests which
match /foo/* will have Debug Level set to ERR and log messages will be logged to
c:/tmp/foo_proxy.log file

 BEA recommends that you use the MatchExpression statement

instead of the <files> block.

Template for the Apache HTTP Server httpd.conf File

This section contains a sample httpd.conf file. You can use this sample as a template
that you can modify to suit your environment and server. Lines beginning with # are
comments. Note that Apache HTTP Server is not case sensitive, and that the
LoadModule and AddModule lines are automatically added by the apxs utility.
####################################################
APACHE-HOME/conf/httpd.conf file
####################################################
LoadModule weblogic_module libexec/mod_wl.so
AddModule mod_weblogic.c
<Location /weblogic>
SetHandler weblogic-handler
PathTrim /weblogic
ErrorPage http://myerrorpage1.mydomain.com
</Location>
<Location /servletimages>
SetHandler weblogic-handler
PathTrim /something
ErrorPage http://myerrorpage1.mydomain.com
</Location>
<IfModule mod_weblogic.c>
MatchExpression *.jsp
WebLogicCluster w1s1.com:7001,w1s2.com:7001,w1s3.com:7001
ErrorPage http://myerrorpage.mydomain.com
</IfModule>

Sample httpd.conf Configuration Files

Instead of defining parameters in the location block of your httpd.conf file, if

you prefer, you can use a weblogic.conf file that is loaded by the IfModule in the
httpd.conf file. The following examples may be used as templates that you can
modify to suit your environment and server. Lines beginning with # are comments.

Example Using WebLogic Clusters

# These parameters are common for all URLs which are
# directed to the current module. If you want to override
# these parameters for each URL, you can set them again in
# the <Location> or <Files> blocks. (Except WebLogicHost,
# WebLogicPort, WebLogicCluster, and CookieName.)
<IfModule mod_weblogic.c>
WebLogicCluster w1s1.com:7001,w1s2.com:7001,w1s3.com:7001
ErrorPage http://myerrorpage.mydomain.com
MatchExpression *.jsp
</IfModule>
####################################################

Example Using Multiple WebLogic Clusters

# These parameters are common for all URLs which are
# directed to the current module. If you want to override
# these parameters for each URL, you can set them again in
# the <Location> or <Files> blocks (Except WebLogicHost,
# WebLogicPort, WebLogicCluster, and CookieName.)
<IfModule mod_weblogic.c>
MatchExpression *.jsp WebLogicHost=myHost|WebLogicPort=7001|Debug=ON
MatchExpression *.html WebLogicCluster=myHost1:7282,myHost2:7283|
ErrorPage=
http://www.xyz.com/error.html
</IfModule>

Example Without WebLogic Clusters

# These parameters are common for all URLs which are
# directed to the current module. If you want to override
# these parameters for each URL, you can set them again in
# the <Location> or <Files> blocks (Except WebLogicHost,
# WebLogicPort, WebLogicCluster, and CookieName.)
<IfModule mod_weblogic.c>
WebLogicHost myweblogic.server.com
WebLogicPort 7001
MatchExpression *.jsp
</IfModule>

Example Configuring IP-Based Virtual Hosting

NameVirtualHost 172.17.8.1
<VirtualHost goldengate.domain1.com>
WebLogicCluster tehama1:4736,tehama2:4736,tehama:4736
PathTrim /x1
ConnectTimeoutSecs 30
</VirtualHost>
<VirtualHost goldengate.domain2.com>
WeblogicCluster green1:4736,green2:4736,green3:4736
PathTrim /y1
ConnectTimeoutSecs 20
</VirtualHost>

Example Configuring Name-Based Virtual Hosting With a Single IP

Address
<VirtualHost 162.99.55.208>
ServerName myserver.mydomain.com
<Location / >
SetHandler weblogic-handler
WebLogicCluster 162.99.55.71:7001,162.99.55.72:7001
Idempotent ON
Debug ON
DebugConfigInfo ON
</Location>
</VirtualHost>
<VirtualHost 162.99.55.208>
ServerName myserver.mydomain.com
<Location / >
SetHandler weblogic-handler
WebLogicHost russell
WebLogicPort 7001
Debug ON
DebugConfigInfo ON
</Location>
</VirtualHost>

Example Configuring Multiple Name-Based Virtual Hosts

# VirtualHost1 = localhost:80
<VirtualHost 127.0.0.1:80>
DocumentRoot "C:/test/VirtualHost1"
ServerName localhost:80 <IfModule mod_weblogic.c>
#... WLS parameter ...
WebLogicCluster localhost:7101,localhost:7201
# Example: MatchExpression *.jsp <some additional parameter>
MatchExpression *.jsp PathPrepend=/test2
</IfModule>
</VirtualHost>
# VirtualHost2 = 127.0.0.2:80
<VirtualHost 127.0.0.2:80>
DocumentRoot "C:/test/VirtualHost1"
ServerName 127.0.0.2:80
<IfModule mod_weblogic.c>
 #... WLS parameter ...
WebLogicCluster localhost:7101,localhost:7201
# Example: MatchExpression *.jsp <some additional parameter>
MatchExpression *.jsp PathPrepend=/test2
#... WLS parameter ...
</IfModule>
</VirtualHost> <IfModule mod_weblogic.c>

You must define a unique value for 'ServerName'or some Plug-In parameters will not
work as expected.

Using SSL with the Apache Plug-In

You can use the Secure Sockets Layer (SSL) protocol to protect the connection between
the Apache HTTP Server Plug-In and WebLogic Server. The SSL protocol provides
confidentiality and integrity to the data passed between the Apache HTTP Server Plug-In
and WebLogic Server.

The Apache HTTP Server Plug-In does not use the transport protocol (http or https)
specified in the HTTP request (usually by the browser) to determine whether or not the
SSL protocol is used to protect the connection between the Apache HTTP Server Plug-In
and WebLogic Server.

Although two-way SSL can be used between the HTTP client and Apache HTTP server,
note that one-way SSL is used between Apache HTTP Server and WebLogic Server.

Implementing Two-way SSL between Apache and the HTTP Client:

1. Configure Apache HTTP Server to request a client certificate. The
certificate is stored as one of the following request attributes:

• javax.net.ssl.peer_certificates

returns a weblogic.security.X509Certificate certificate

• java.security.cert.X509Certificate

returns a java.security.cert.X509 certificate

2. Access the certificate by reading the request attribute, for example:

request.getAttribute("javax.net.ssl.peer_certificates");

3. In WebLogic Server, authenticate the user with the

weblogic.security.acl.certAuthenticator.authenticate() method.

Configuring SSL Between the Apache HTTP Server Plug-In and

WebLogic Server

To use the SSL protocol between Apache HTTP Server Plug-In and WebLogic Server:
 1. Configure WebLogic Server for SSL. For more information, see
Configuring the SSL Protocol.

2. Configure the WebLogic Server SSL listen port. For more

information, see Configuring the SSL Protocol.

3. In the Apache Server, set the WebLogicPort parameter in the

httpd.conf file to the listen port configured in step 2.

4. In the Apache Server, set the SecureProxy parameter in the

httpd.conf file to ON.

5. Set any additional parameters in the httpd.conf file that define

information about the SSL connection. For a complete list of parameters, see
SSL Parameters for Web Server Plug-Ins

Specifying Trust for the WL-Proxy-Client-Cert Header

The plug-in can encode users' identity certifications in the WL-Proxy-Client-Cert

header and pass the header to WebLogic Server instances (see Proxying Requests to
Another Web Server). A WebLogic Server instance uses the certificate information from
that header, trusting that it comes from a secure source (the Plug-In), to authenticate the
user. In previous releases of WebLogic Server, the default behavior was to always trust
the WL-Proxy-Client-Cert header. Beginning with WebLogic Server 6.1 SP2, you
need to explicitly define trust of the WL-Proxy-Client-Cert header. A new
parameter, clientCertProxy, allows WebLogic Server to determine whether to trust
the certificate header. For an additional level of security, use a connection filter to limit
all connections into WebLogic Server (therefore allowing WebLogic Server to only
accept connections from the machine on which the plug-in is running).

The clientCertProxy parameter has been added to the HTTPClusterServlet

and Web applications.

For the HTTPClusterServlet, add the parameter to the web.xml file as follows:

<context-param>
<param-name>clientCertProxy</param-name>
<param-value>true</param-value>
</context-param>

For Web applications, add the parameter to the web.xml file as follows:

ServletRequestImpl context-param
<context-param>
<param-name>weblogic.httpd.clientCertProxy</param-name>
<param-value>true</param-value>
</context-param>

You can also use this parameter in a cluster as follows:

<Cluster ClusterAddress="127.0.0.1" Name="MyCluster"

ClientCertProxyHeader="true"/>
This parameter can be used with a third party proxy server such as a load balancer or an
SSL accelerator to enable 2-way SSL authentication.

Issues with SSL-Apache Configuration

The following known issues may arise when you configure the Apache plug-in to use
SSL:

 To prepare the plugin configuration, double click the lock and go to

the certificates path:

* Select the root CA (at the top)

* Display it

* Detail and then copy this certificate to a file using the Coded "Base

64 X509" option

* Save the file, for example, to ýMyWeblogicCAToTrust.cerý (which

is also a PEM file)

 The PathTrim parameter must be configured inside the <Location>

tag.

The following configuration is incorrect:

<Location /weblogic>
SetHandler weblogic-handler
</Location>
<IfModule mod_weblogic.c>
WebLogicHost localhost
WebLogicPort 7001
PathTrim /weblogic
</IfModule>

The following configuration is the correct setup:

<Location /weblogic>
SetHandler weblogic-handler
PathTrim /weblogic
</Location>

 The Include directive does not work with Apache SSL. You must
configure all parameters directly in the httpd.conf file. Do not use the
following configuration when using SSL:

<IfModule mod_weblogic.c>
MatchExpression *.jsp
Include weblogic.conf
</IfModule>

 If you use precompiled OpenSSL from Sunfreeware.com, failover

may not work properly when the plug-in tries to connect to a backend
 instance of WebLogic Server. If you encounter such a failure, rebuild
OpenSSL and modssl and Apache using the following configuration settings.
• For building OpenSSL:

./Configure solaris-sparcv8-gcc -fexceptions

--prefix=/home/egross/solaris/ssl shared
make
make install

• For building modssl and Apache:

cd ..
cd mod_ssl-2.8.12-1.3.27
export LD_LIBRARY_PATH=/home/egross/solaris/ssl/lib
./configure "--with-apache=../apache_1.3.27"
"--with-ssl=/home/egross/solaris/ssl" "--
prefix=/usr/local/apache_so"
"--enable-rule=SHARED_CORE" "--enable-shared=ssl" "--
enable-module=so" "$@"
cd ../apache_1.3.27
make
make install

 The current implementation of the WebLogic Server Apache plug-in

does not support the use of multiple certificate files with ApacheSSL.

Connection Errors and Clustering Failover

When the Apache HTTP Server Plug-In attempts to connect to WebLogic Server, the
plug-in uses several configuration parameters to determine how long to wait for
connections to the WebLogic Server host and, after a connection is established, how long
the plug-in waits for a response. If the plug-in cannot connect or does not receive a
response, the plug-in attempts to connect and send the request to other WebLogic Server
instances in the cluster. If the connection fails or there is no response from any WebLogic
Server in the cluster, an error message is sent.

Figure 2-1 demonstrates how the plug-in handles failover.

Possible Causes of Connection Failures

Failure of the WebLogic Server host to respond to a connection request could indicate
possible problems with the host machine, networking problems, or other server failures.

Failure of all WebLogic Server instances to respond, could indicate that WebLogic
Server is not running or is unavailable, a hung server, a database problem, or other
application failure.

Failover with a Single, Non-Clustered WebLogic Server

If you are running only a single WebLogic Server instance the plug-in only attempts to
connect to the server defined with the WebLogicHost parameter. If the attempt fails, an
HTTP 503 error message is returned. The plug-in continues trying to connect to that
same WebLogic Server instance until ConnectTimeoutSecs is exceeded.
 The Dynamic Server List

When you specify a list of WebLogic Servers in the WebLogicCluster parameter, the
plug-in uses that list as a starting point for load balancing among the members of the
cluster. After the first request is routed to one of these servers, a dynamic server list is
returned containing an updated list of servers in the cluster. The updated list adds any
new servers in the cluster and deletes any that are no longer part of the cluster or that
have failed to respond to requests. This list is updated automatically with the HTTP
response when a change in the cluster occurs.

Failover, Cookies, and HTTP Sessions

When a request contains a session information stored in a cookie, in the POST data, or by
URL encoding, the session ID contains a reference to the specific server instance in
which the session was originally established (called the primary server) and a reference
to an additional server where the original session is replicated (called the secondary
server). A request containing a cookie attempts to connect to the primary server. If that
attempt fails, the request is routed to the secondary server. If both the primary and
secondary servers fail, the session is lost and the plug-in attempts to make a fresh
connection to another server in the dynamic cluster list. For more information, see
Figure 2-1 Connection Failover.

Note: If the POST data is larger than 64K, the plug-in will not parse the POST data to
obtain the session ID. Therefore, if you store the session ID in the POST data, the plug-in
cannot route the request to the correct primary or secondary server, resulting in possible
loss of session data.

Figure 2-1 Connection Failover

Notes: The HTTP error code thrown by the plug-in depends on the situation. Plug-in will
return the HTTP error code 500 in the following conditions:

 Neither WebLogicCluster nor WebLogicPort was specified in the

httpd.conf file.
 Unable to resolve the WebLogicHost parameter specified in the
httpd.conf file.
 Port number specified by WebLogicPort, in the httpd.conf file,
exceeds 65535.
 Unsuccessful in parsing the request while applying the PathTrim
property.
 The request header is of type Unknown Transfer-Encoding.
Failed to read the chunked request.
 Encounetered an error reading POST data from client.
 Failed to open a temporary(temp) file.
 Failed to write POST data to the temp file.
 Encounetered an error reading POST data from the temp file.
 POST timed out.
 SSL was specified without the parameter trustedCAFile.

On the other hand, the HTTP error code 503 is returned when:

 The maximum number of retries is exceeded. This value is computed

by dividing ConnectTimeoutSecs by ConnectRetrySecs.
 Idempotent is OFF.

Create JDBC data sources

Before you begin

Make sure that the JDBC drivers that you want to use to create database connections are
installed on all servers on which you want to deploy the data source. Some JDBC drivers
are installed with WebLogic Server, including BEA WebLogic Type 4 JDBC drivers for
DB2, Informix, MS SQL Server, Oracle, and Sybase. For more information about
working with JDBC drivers, see Using Third-Party JDBC Drivers with WebLogic Server

In WebLogic Server, you configure database connectivity by adding JDBC data sources
to your WebLogic domain. A data source is a J2EE standard method of configuring
connectivity to a database. Each WebLogic data source contains a pool of database
connections. Applications look up the data source on the JNDI tree or in the local
application context and then reserve a database connection with the getConnection
method. Data sources and their connection pools provide connection management
processes that help keep your system running and performant.

To create a JDBC data source:

1. If you have not already done so, in the Change Center of the
Administration Console, click Lock & Edit (see Use the Change Center).

2. In the Domain Structure tree, expand Services > JDBC, then select
Data Sources.
3. On the Summary of Data Sources page, click New.

4. On the JDBC Data Source Properties page, enter or select the following
information:

Name - Enter a name for this JDBC data source. This name is used in
the configuration file (config.xml) and throughout the Administration
Console whenever referring to this data source.
JNDI Name - Enter the JNDI path to where this JDBC data source will
be bound. Applications look up the data source on the JNDI tree by
this name when reserving a connection.
Database Type - Select the DBMS of the database that you want to
connect to. If your DBMS is not listed, select Other.
Database Driver - Select the JDBC driver you want to use to connect
to the database. The list includes common JDBC drivers for the
selected DBMS.
Note: You must install JDBC drivers before you can use them to create
database connections. Some JDBC drivers are installed with WebLogic
Server, but many are not installed.
Click Next to continue.

5. On the Transactions Options page, follow these steps:

a. Select global transaction options:

Supports Global Transactions - Select this check box (the

default) to enable global transaction support in this data
source. Clear this check box to disable (ignore) global
transactions in this data source. In most cases, you should
leave the option selected. See Transaction Options.
If you selected Supports Global Transactions, select an
option for transaction processing: (available options vary
depending on whether you select an XA driver or a non-XA
driver)

 Two-Phase Commit - Select this option to enable

standard XA processing.

This option is only available when you select an XA

JDBC driver to make database connections.

 Logging Last Resource - Select this option to

enable a non-XA JDBC connection to participate in global
transactions using the Logging Last Resource (LLR)
transaction optimization. Recommended in place of
Emulate Two-Phase Commit.

This option is only available when you select a non-

XA JDBC driver to make database connections.

 Emulate Two-Phase Commit - Enables a non-XA

JDBC connection to emulate participation in distributed
transactions using JTA. Select this option only if your
application can tolerate heuristic conditions.
 This option is only available when you select a non-
XA JDBC driver to make database connections.

 One-Phase Commit - Select this option to enable

the non-XA connection to participate in a global transaction
as the only transaction participant.

This option is only available when you select a non-

XA JDBC driver to make database connections.
For more information about transaction options, see
Transaction Options

b. Optionally, select Supports Local Transactions if the XA JDBC

driver you selected supports local transactions as well as global
transactions.

Click Next to continue.

2. On the Connection Properties page, enter values for the following

properties:

Database Name - Enter the name of the database that you want to
connect to. Exact database name requirements vary by JDBC driver
and by DBMS.
Host Name - Enter the DNS name or IP address of the server that
hosts the database.
Port - Enter the port on which the database server listens for
connections requests.
Database User Name - Enter the database user account name that
you want to use for each connection in the data source.
Password/Confirm Password - Enter the password for the database
user acccount.
Click Next to continue.

3. On the Test Database Connection page, review the connection parameters

and click Test Configuration.

WebLogic attempts to create a connection from the Administration

Server to the database. Results from the connection test are displayed
at the top of the page. If the test is unsuccessful, you should correct
any configuation errors and retry the test.
If the JDBC driver you selected is not installed on the Administration
Server, you should click Next to skip this step.
Click Next to continue.

4. On the Select Targets page, select the servers or clusters on which you
want to deploy the data source.

5. Click Finish to save the JDBC data source configuration and deploy the
data source to the targets that you selected.

6. To activate these changes, in the Change Center of the Administration

Console, click Activate Changes.
 Not all changes take effect immediately—some require a restart (see Use the
Change Center).

Tuning the Memory Management System

Memory management is all about allocation of objects. One part of the memory
management system finds a free spot for the new object, while another part
garbage collects old objects to create more free space for new objects. The more
objects a Java application allocates, the more resources will be used for memory
management. A correctly tuned memory management system minimizes the
overhead inflicted by garbage collection and makes object allocation fast. You
can read more about how memory management in BEA JRockit works in
Understanding Memory Management. This section covers the most important
options available for tuning the memory management system in BEA JRockit.
The following topics are covered:

 Setting the Heap and Nursery Size

 Selecting and Tuning a Garbage Collector

 Tuning the Compaction of Memory

 Optimizing Memory Allocation Performance

 Getting Help on Memory Management Issues

Setting the Heap and Nursery Size

The heap is the area where the Java objects reside. The heap size has an impact
on the JVM's performance, and thus also on the Java application's performance.
When the JVM uses a generational garbage collection strategy, a part of the
heap is reserved for the nursery. All small objects are allocated in the nursery,
also known as young space. When the nursery becomes full, a young collection
is performed, where objects that have lived long enough in the nursery are
moved to old space, which is the rest of the heap.
To distinguish between recently allocated objects and objects that have been
around for a while in the nursery, the JVM uses a keep area. The keep area
contains the most recently allocated objects in the nursery and is not garbage
collected until the next young collection.

Setting the Heap Size

Command line options: -Xms:<min size> -Xmx:<max size>

The heap size has an impact on allocation speed, garbage collection frequency
and garbage collection times. A small heap will become full quickly and must be
garbage collected more often. It is also prone to more fragmentation, making
object allocation slower. A large heap introduces a slight overhead in garbage
collection times. A heap that is larger than the available physical memory in the
system must be paged out to disk, which leads to long access times or even
application freezes, especially during garbage collection.
In general, the extra overhead caused by a larger heap is smaller than the gains
in garbage collection frequency and allocation speed, as long as the heap
doesn't get paged to disk. Thus a good heap size setting would be a heap that is
as large as possible within the available physical memory.
 There are two parameters for setting the heap size:

 -Xms:<size>, which sets the initial and minimum heap size

 -Xmx:<size>, which sets the maximum heap size

For example:
java -Xms:1g -Xmx:1g MyApplication

This starts up the JVM with a heap size fixed to 1 GB.

For default values and limitations, see the documentation on -Xms and -Xmx.

If the optimal heap size for the application is known, we recommend that you
set -Xms and -Xmx to the same value. This gives you a controlled environment
where you get a good heap size right from the start.

Setting the Heap Size on 64-bit Systems

On 64-bit systems a memory address is 64 bits long, which makes it possible to
address much more memory than with a 32-bit address. On the other hand each
reference requires twice as much memory. To reduce the memory usage on 64-
bit systems, BEA JRockit can use compressed references. Compressed
references reduce the references to 32 bits, and can be used as long as the
entire heap can be addressed with 32 bits. Compressed references are enabled
by default whenever applicable. Thus, on a 64.bit system, you will usually
benefit from setting the maximum heap size below 4 GB as long as the amount
of live data is less than 3-4 GB.

Setting the Nursery and Keep Area Size

Command line option: -Xns:<nursery size>

The size of the nursery has an impact on allocation speed, garbage collection
frequency and garbage collection times. A small nursery will become full quickly
and must be garbage collected more often, while garbage collection of a large
nursery takes slightly longer time. A nursery that is so small that few or no
objects have died before a young collection is started is of very little use, and
neither is a nursery that is so large that no young collections are performed
between garbage collections of the whole heap that are triggered due to
allocation of large objects in old space.
An optimal nursery size for maximum application throughput is such that as
many objects as possible are garbage collected by young collection rather than
old collection. This value approximates to about half of the free heap. In BEA
JRockit R27.3.0 and later releases, the dynamic garbage collection mode
optimized for throughput, -Xgcprio:throughput, and the static generational
parallel garbage collector, -Xgc:genpar, will dynamically set the nursery size to
an approximation of the optimal value.
The optimal nursery size for throughput is often quite large, which may lead to
long young collection times. Since all Java threads are paused while the young
collection is performed, you may want to reduce the nursery size below the
optimal value to reduce the young collection pause times.
The nursery size is set using the command line option -Xns:<size>. For
example:
java -Xns:100m MyApplication

This starts up the JVM with a fixed nursery size of 100 MB.
 For default values and limitations, see the documentation on -Xns.

Keep Area
Command line option: -XXkeepAreaRatio:<percentage>

The keep area size has an impact on both old collection and young collection
frequency. A large keep area causes more frequent young collections, while a
keep area that is too small causes more frequent old collections when objects
are promoted prematurely.
An optimal keep area size is as small as possible while maintaining a low
promotion ratio. The promotion ratio can be observed in JRA recordings (see
Using Mission Control Tools for more information) and verbose outputs from
-Xverbose:memory=debug, as well as in the garbage collection report printed out
by -XgcReport. By default the keep area is 25% of the nursery.

The keep area size can be changed using the command line option
-XXkeepAreaRatio:<percentage>, and is defined as a percentage of the
nursery. For example:
java -XXkeepAreaRatio:10 MyApplication

This starts up the JVM with a keep area that is 10% of the nursery size.

Selecting and Tuning a Garbage Collector

Garbage collection of objects is a necessary evil. Without garbage collection the
automatic memory management system would not work, and either the
application developers would have to somehow recycle the memory themselves
or the application would after a while use up all the memory in the system until
it can't continue running as further memory allocation becomes impossible.
The impact of garbage collection can be distributed in different ways depending
on the choice of the garbage collection method. BEA JRockit offers several
garbage collection modes, which use one or several garbage collection
strategies. The garbage collection modes are either dynamic, which select the
best garbage collection strategy for a given goal, or static, allowing the user to
select a garbage collection strategy of their choice. You can select a dynamic
garbage collection mode by using the command line option -XgcPrio:<mode>, or
set a static garbage collector with -Xgc:<strategy>.

Selecting a Dynamic Garbage Collection Mode

The dynamic garbage collection modes adjust the memory management system
in runtime, optimizing for a specific goal depending on which mode is used.
There are three dynamic garbage collection modes:

 throughput, which optimizes the garbage collector for maximum

application throughput

 pausetime, which optimizes the garbage collector for short and even
pausetimes

 deterministic, which optimizes the garbage collector for very short and
deterministic pause times

The dynamic garbage collection modes use advanced heuristics to tune the
following parameters in runtime:
  Garbage collection strategy

 Nursery size

 Compaction amount and type

Use a dynamic garbage collection mode if you don't want to go through the time
consuming process of tuning these parameters manually, or when a static
environment isn't optimal for your application.

Throughput Mode
Command line option: -XgcPrio:throughput

The dynamic garbage collection mode optimizing over application throughput

uses as little CPU resources as possible for garbage collection, thus giving the
Java application as many CPU cycles as possible. BEA JRockit achieves this by
using a parallel garbage collection strategy that stops the Java application
during the whole garbage collection duration and uses all CPUs available to
perform the garbage collection. Each individual garbage collection pause may be
long, but in total the garbage collector takes as little CPU time as possible.
Use throughput mode for applications that demand a high throughput but are
not very sensitive to the occasional long garbage collection pause.
Throughput mode is default when BEA JRockit runs in -server mode (which is
default), or can be enabled with the command line option
-XgcPrio:throughput. For example:
java -XgcPrio:throughput MyApplication

This starts up the JVM with the garbage collection mode optimized for
throughput.
For more information, see the documentation on -XgcPrio.

Pausetime Mode
Command line option: -XgcPrio:pausetime

The dynamic garbage collection mode optimizing over pause times aims to keep
the garbage collection pauses below a given pause target while maintaining as
high throughput as possible. BEA JRockit achieves this by choosing between a
mostly concurrent garbage collection strategy that allows the Java application to
continue running during large portions of the garbage collection duration, and a
parallel garbage collection strategy that stops the Java application during the
entire garbage collection duration. The mostly concurrent garbage collector
introduces some extra overhead in keeping track of changes during the
concurrent phases, and will also cause more frequent garbage collections. This
will lower the overall throughput somewhat, but keeps down the individual
garbage collection pauses.
Use pausetime mode for applications that are sensitive to long latencies, for
example transaction based systems where transaction times must be stable.
Pausetime mode is enabled with the command line option -XgcPrio:pausetime.
For example:
java -XgcPrio:pausetime MyApplication

This starts up the JVM with the garbage collection mode optimized for short
pauses.
 For more information, see the documentation on -XgcPrio.

Setting a Pause Target for Pausetime Mode

Command line option: -XpauseTarget:<time in ms>

The pausetime mode uses a pause target for optimizing the pause times. The
pause target impacts the application throughput, as a lower pause target will
inflict more overhead on the memory management system. Set the pause target
as high as your application can tolerate.
The pause target for pausetime mode is by default 500 ms, and can be changed
with the command line option -XpauseTarget:<time in ms>. For example:
java -XgcPrio:pausetime -XpauseTarget:300ms MyApplication

This starts up the JVM with the garbage collection optimized for short pauses
and a pause target of 300 ms.
For more information, see the documentation on -XpauseTarget.

Deterministic Mode
Command line option: -XgcPrio:deterministic

Note: This feature is available only as part of BEA WebLogic Real Time. If
you attempt to enable it without the proper license, or with an invalid
or expired license, a warning message will be written to the console.

The dynamic garbage collection mode optimizing for deterministic pause times is
designed to ensure extremely short garbage collection pause times and limit the
total pause time within a prescribed window. BEA JRockit achieves this by using
a specially designed mostly concurrent garbage collector, which allows the Java
application to continue running as much as possible during the garbage
collection.
Use the deterministic mode for applications with strict demands on short and
deterministic latencies, for example transaction based applications.
Deterministic mode is enabled with the command line option
-XgcPrio:deterministic. For example:
java -XgcPrio:deterministic MyApplication

This starts up the JVM with the garbage collection mode optimized for short and
deterministic pauses.
For more information, see the documentation on -XgcPrio.

Special Note for WLRT Users

Deterministic garbage collection time can be affected by JRockit Mission Control
(JMC). While all JMC tools are fully supported when running WLRT with the
deterministic garbage collector, you should be aware of some caveats.

 -Xmanagement does not prolong deterministic garbage collection pauses

by itself, but it does introduce a slightly increased amount of Java code
executed by the JVM. This can affect response times and performance
compared to not using -Xmanagement.

 When making a JRA-recording, disable heap statistics (heapstat) if you run

in a latency sensitive situation where you cannot accept the pause for the
benefit of the information. Heapstat provides additional bookkeeping of the
 content of the heap. These statistics are collected at the beginning and at the
end of a JRA-recording, inside a pause. You can disable heapstat by using
specific arguments when requesting the recording. For more information,
please see Creating a JRA Recording with BEA JRockit Mission Control 1.0.

 JRA recordings, even with heapstats disabled, might cause deterministic

garbage collection pauses to last slightly longer.

 Memory leak trend analysis can cause longer garbage collection pauses,
similar to JRA recordings.

 On requests for more information when the Memory Leak Detector is using
its graphical user interface or the Ctrl-Break handler—for example to retrieve
the number of instances of a type of object or to retrieve the list of references
to an instance or to a class—a longer pause can be introduced.

For more information on JRockit Mission Control, please refer to Using Mission
Control Tools.

Setting a Pause Target for Deterministic Mode

Command line option: -XpauseTarget:<time in ms>

The deterministic mode uses a pause target for optimizing the pause times. The
pause target impacts the application throughput, as a lower pause target will
inflict more overhead on the memory management system. Set the pause target
as high as your application can tolerate.
The garbage collector will aim on keeping the garbage collection pauses below
the given pause target. How well it will succeed depends on the application and
the hardware. For example, a pause target on 30 ms has been verified on an
application with 1 GB heap and an average of 30% live data or less at collection
time, running on the following hardware:

 2 x Intel Xeon 3.6 GHz, 2 MB level 2 cache, 4 GB RAM

 4 x Intel Xeon 2.0 GHz, 0.5 MB level 2 cache, 8 GB RAM

Running on slower hardware, with a different heap size and/or with more live
data might break the deterministic behavior or cause performance degradation
over time, while faster hardware or less live data might allow you to set a lower
pause target.
The pause target for deterministic mode is by default 30 ms, and can be
changed with the command line option -XpauseTarget:<time>. For example:
java -XgcPrio:deterministic -XpauseTarget:40ms MyApplication

This starts up the JVM with the garbage collection optimized for short and
deterministic pauses and a pause target of 40ms.
For more information, see the documentation on -XpauseTarget.

Selecting a Static Garbage Collection Strategy

Command line option: -Xgc:<strategy>

There are four major static garbage collection strategies available.

 singlepar, which is a single-generational parallel garbage collector

(same as parallel)
  genpar, which is a two-generational parallel garbage collector

 singlecon, which is a single-generational mostly concurrent garbage

collector

 gencon, which is a two-generational mostly concurrent garbage collector

When a static garbage collection strategy is selected, the garbage collection

strategy will not change automatically in runtime.
Use a static garbage collection strategy if you want a well defined and
predictable behavior and are willing to tune the JVM to find the best memory
management settings for your application.

Garbage Collector Strategy Selection Workflow

To select the best garbage collection strategy for your application you can follow
this workflow:
1. Is your application sensitive to long garbage collection pauses (500 ms or
more)?

 Yes: Select a mostly concurrent garbage collection strategy, gencon or

singlecon

 No: Select a parallel garbage collection strategy, genpar or singlepar

1. Does your application allocate a lot of temporary objects?

 Yes: Select a two-generational garbage collection strategy, gencon or

genpar

 No: Select a single-generational garbage collection strategy, singlecon

or singlepar

For example, the BEA WebLogic Sip Server is a transaction based system that
allocates new objects for each transaction and has short time-outs for
transactions. Long garbage collection pauses would cause transactions to time
out, so a mostly concurrent garbage collection should be used. This suggests
either gencon or singlecon. The transactions generate a lot of temporary or
short lived objects, which suggests a two-generational garbage collector,
gencon.

You can set a static garbage collection strategy with the command line option
-Xgc:<strategy>, for example:
java -Xgc:gencon MyApplication

This starts up the JVM with the generational concurrent garbage collector.
For more information, see the documentation on -Xgc.

Changing Garbage Collection Strategy During Runtime

You can change garbage collector strategies during runtime from the Memory
tab of the BEA JRockit Management Console (in Mission Control) except for when
these conditions exist:

 If you are using the dynamic garbage collection mode optimized for
deterministic pause times.
  If you are using static single-spaced parallel garbage collection.

For more information, consult BEA JRockit Management Console's online help.

Tuning the Concurrent Garbage Collection Trigger

Command line option: -XXgcTrigger:<percentage>

When you are using a concurrent strategy for garbage collection (in either the
mark or the sweep phase, or both), BEA JRockit dynamically adjusts when to
start an old generation garbage collection in order to avoid running out of free
heap space during the concurrent phases of the garbage collection. The
triggering is based on such characteristics as how much space is available on the
heap after previous collections. BEA JRockit dynamically tries to optimize this
space and will occasionally run out of free heap during the concurrent garbage
collection while it does. When the limit is hit, the verbose printout:

[memdbg ] starting parallel sweeping phase

appears below the command line (assuming you have set -Xverbose:memdbg).
This message means that a concurrent sweep could not finish in time and the
JVM is using all currently available resources to make up for it. In this case, a
parallel sweep is made. If BEA JRockit fails to adapt and the above printout
continues to appear, performance is being adversely affected. To avoid this, set
the -XXgcTrigger option to trigger a garbage collection when there is still X%
left of the heap, for example:

java -XXgcTrigger=20 MyApplication

will trigger an old generation garbage collection when less than 20% of the free
heap size is left unused.
If you are using a parallel garbage collection strategy (in both the mark and the
sweep phase), then old generation garbage collections are performed whenever
the heap is completely full.

Tuning the Compaction of Memory

Compaction is the process of moving chunks of allocated space towards the
lower end of the heap, helping create contiguous free memory at the upper end.
BEA JRockit does partial compaction of the heap at each old collection. The size
and position of the compaction area as well as the compaction method is
selected by advanced heuristics, depending on the garbage collection mode
used.

Fragmentation vs. Garbage Collection Pauses

Compaction is performed during garbage collection while all Java threads are
paused. Compaction of a large area with many objects will thus increase the
garbage collection pause times. On the other hand, insufficient compaction will
lead to fragmentation of the heap, which leads to lower performance. If the
fragmentation increases over time, BEA JRockit will eventually be forced to
either do a full compaction of the heap, causing a long garbage collection pause,
or throw an OutOfMemoryError.
If your application shows performance degradation over time in a periodic
manner, such that the performance degrades until it suddenly pops back to
excellent, just to start degrading again, you are most likely experiencing
fragmentation problems. The heap becomes more and more fragmented for
 each old collection until finally object allocation becomes impossible and the JVM
is forced to do a full compaction of the heap. The full compaction eliminates the
fragmentation, but only until the next garbage collection. You can verify this by
looking at -Xverbose:memory outputs, monitoring the JVM through the Console
in Mission Control or by creating a JRA recording and examining the garbage
collection data. If you see that the amount of used heap after each old collection
keeps increasing over time until it hits the roof, and then drops down again at
the next old collection, you are experiencing a fragmentation problem.
Compaction is optimally tuned when the fragmentation is kept on a low and
constant level.

Adjusting Compaction
Even though the compaction heuristics in BEA JRockit are designed to keep the
garbage collection pauses low and even, you may sometimes want to limit the
compaction ratio further to reduce the garbage collection pauses. In other cases
you may want to increase the compaction ratio to keep heap fragmentation in
control. There are several ways to adjust the compaction:

 Setting the Compaction Ratio

 Setting the Compact Set Limit

 Turning Off Compaction

 Using Full Compaction

Setting the Compaction Ratio

Command line option: -XXcompactRatio:<percentage>

Setting a static compaction ratio will force BEA JRockit to compact a specified
percentage of the heap at each old collection. This disables the heuristics for
selecting a dynamic compaction ratio that depends on the heap layout. The
compact ratio can be defined to a static percentage of the heap using the
command line option -XXcompactRatio:<percentage>. For example:
java -XXcompactRatio:1 MyApplication

This starts up the JVM with a static compact ratio of about 1% of the heap.
For more information, see the documentation on -XXcompactRatio.

Use this option if you need to force BEA JRockit to use a smaller or larger
compaction ratio than it would select by default. You can monitor the
compaction ratio in -Xverbose:memory=debug outputs and JRA recordings. A
high compaction ratio keeps down the fragmentation on the heap but increases
the compaction pause times.

Setting the Compact Set Limit

Command line option: -XXcompactSetLimit:<references>

When compaction has moved objects, the references to these objects must be
updated. The garbage collector does this before the Java threads are allowed to
run again, which increases the garbage collection pause proportionally to the
number of references that have been updated. The compact set limit defines
how many references there may be from objects outside the compaction area to
objects within the compaction area, thus limiting a portion of the compaction
 pause. If, during a garbage collection, the number of references to the chosen
compaction area exceeds the compact set limit, the compaction will be canceled.
The compact set limit depends on the garbage collection mode used, and will for
some modes adjust dynamically in runtime. You can set a static compact set
limit by using the command line option -XXcompactSetLimit:<references>,
where "references" specifies the maximum number of references to objects
within the compaction area. For example:
java -XXcompactSetLimit:20000 MyApplication

This starts up the JVM with a compact set limit of 20000 references.
For more information, see the documentation for -XXcompactSetLimit.

Use this option to increase the compact set limit if too many compactions are
canceled (aborted), or to decrease the limit if the compaction pause times are
too long. You can monitor the compaction behavior in -Xverbose:memory=debug
outputs and JRA recordings, and compaction pause times in
-Xverbose:gcpause=debug outputs and JRA recordings.

Note: -XXcompactSetLimit has no effect when the deterministic or

pausetime garbage collection modes are used, as these garbage
collector modes use other heuristics for adjusting the compaction
pausetimes.

Turning Off Compaction

Command line option: -XXnoCompaction

Very few applications survive in the long run without any compaction at all, but
for those that do you can turn off the compaction entirely.
To turn off compaction entirely, use the command line option -XXnoCompaction,
for example:
java -XXnoCompaction MyApplication

For more information, see the documentation for -XXnoCompaction.

Using Full Compaction

Command line option: -XXfullCompaction

Some applications are not sensitive to garbage collection pauses or perform old
collections very infrequently. For these applications you may want to try running
full compaction, as this maximizes the object allocation performance between
the garbage collections. Note however that a full compaction of a large heap
with a lot of objects may take several seconds to perform.
To turn on full compaction, use the command line option -XXfullCompaction,
for example:
java -XXfullCompaction MyApplication

For more information, see the documentation for -XXfullCompaction.

Optimizing Memory Allocation Performance

Apart from optimizing the garbage collection to clear space for object allocation,
you can tune the object allocation itself to maximize the application throughput.
Setting the Thread Local Area Size
Command line options: -XXtlaSize:min=<size>,preferred=<size>
-XXlargeObjectLimit:<size> -XXminBlockSize:<size>

The thread local area (TLA) is a chunk of free space reserved on the heap or in
the nursery and given to a thread for its exclusive use. A thread can allocate
small objects in its own TLA without synchronizing with other threads. Objects
allocated in a TLA are however not thread local. They can be accessed by any
thread and will be garbage collected globally. When the TLA gets full the thread
simply requests a new TLA.
The thread local area size influences the allocation speed, but can also have an
impact on garbage collection frequency. A large TLA size allows each thread to
allocate a lot of objects before requesting a new TLA, and in BEA JRockit R27.2
and later it also allows the thread to allocate larger objects in the thread local
area. On the other hand, a large TLA size prevents small chunks of free memory
from being used for object allocation, which increases the impact of
fragmentation. In BEA JRockit R27.1 and later, the TLA size is dynamic
depending on the size of the available chunks of free space, and varies between
a minimum and a preferred size.
Increasing the preferred TLA size is beneficial for applications where each thread
allocates a lot of objects. When a two-generational garbage collection strategy is
used, a large minimum and preferred TLA size will also allow larger objects to be
allocated in the nursery. Note however that the preferred TLA size should always
be less than about 5% of the nursery size.
Increasing the minimum TLA size may improve garbage collection times slightly,
as the garbage collector can ignore any free chunks that are smaller than the
minimum TLA size.
Decreasing the preferred TLA size is beneficial for applications where each
thread allocates only a few objects before it is terminated, so that a larger TLA
wouldn't ever become full. A small preferred TLA size is also beneficial for
applications with very many threads, where the threads don't have time to fill
their TLAs before a garbage collection is performed.
Decreasing the minimum TLA size lessens the impact of fragmentation.
A common setting for the TLA size is a minimum TLA size of 2-4 kB and a
preferred TLA size of 16-256 kB.
To adjust the TLA size, you can use the command line option
-XXtlaSize:min=<size>,preferred=<size>. For example:
java -XXtlaSize:min=1k,preferred=512k MyApplication

This starts up the JVM with a minimum TLA size of 1 kB and a preferred TLA size
of 512 kB.
For more information and default values, see the documentation on -XXtlaSize.

Note: If you are using BEA JRockit R27.1 or older and want to adjust the
TLA size, you should set -XXlargeObjectLimit:<size> and
-XXminBlockSize:<size> to the same value as the minimum TLA
size.

Note: If you are using BEA JRockit R27.0 or older the minimum and
preferred TLA size will always be the same value. The syntax for
 setting the TLA size is -XXtlaSize:<size>.

Tuning WebLogic Server

The following sections describe how to tune WebLogic Server to match your application
needs.

 Setting Java Parameters for Starting WebLogic Server

 Setting Performance-Related Configuration Parameters
 Development vs. Production Mode Default Tuning Values
 Using WebLogic Server "Native IO" Performance Packs
 Tuning the Default Execute Queue Threads
 Tuning Connection Backlog Buffering
 How JDBC Connection Pools Enhance Performance
 Setting Your Java Compiler
 Using WebLogic Server Clusters to Improve Performance
 Monitoring a WebLogic Server Domain

Setting Java Parameters for Starting WebLogic Server

Java parameters must be specified whenever you start WebLogic Server. For simple
invocations, this can be done from the command line with the weblogic.Server
command. However, because the arguments needed to start WebLogic Server from the
command line can be lengthy and prone to error, BEA recommends that you incorporate
the command into a script. To simply this process, you can modify the default values in
the sample scripts that are provided with the WebLogic distribution to start WebLogic
Server, as described in "Specifying Java Options for a WebLogic Server Instance".

If you used the Configuration Wizard to create your domain, the WebLogic startup
scripts are located in the domain-name directory where you specified your domain. By
default, this directory is BEA_HOME\user_projects\domain\domain-name, where
BEA_HOME is the directory that contains the product installation, and domain-name is
the name of the domain directory defined by the selected configuration template. For
more information about creating domains using the Configuration Wizard, see "Creating
Domains Using the Configuration Wizard".

You need to modify some default Java values in these scripts to fit your environment and
applications. The important performance tuning parameters in these files are the
JAVA_HOME parameter and the Java heap size parameters:

 Change the value of the variable JAVA_HOME to the location of your JDK. For
example:

set JAVA_HOME=C:\bea\jdk141_03

 For higher performance throughput, set the minimum java heap size equal to the
maximum heap size. For example:

"%JAVA_HOME%\bin\java" -hotspot -Xms512m -Xmx512m -classpath

%CLASSPATH% -
 See Specifying Heap Size Values for details about setting heap size options.

Setting Performance-Related Configuration Parameters

The WebLogic Server configuration file (config.xml) contains a number of

performance-related parameters that can be fine-tuned depending on your environment
and applications. Tuning these parameters based on your system requirements (rather
than running with default settings) can greatly improve both single-node performance and
the scalability characteristics of an application.

Within a WebLogic Server domain, the configuration file is located on the machine that
hosts the Administration Server, and provides persistent storage of WebLogic MBean
attribute values. The Administration Server serves as a central point of contact for server
instances and system administration tools. A domain may also include additional
WebLogic Server instances called Managed Servers, which are used mainly for servicing
applications.

When the Administration Server starts, it reads the domain configuration file and
overrides the default attribute values of the administration MBeans with any attribute
values found in the configuration file. Every time you change an attribute using the
system administration tools (using either the command-line interface or the
Administration Console), its value is stored in the appropriate administration MBean and
written to the configuration file.

For more information about system administration infastructure, see "Overview of

WebLogic Server System Administration" in the Administration Guide.

Overview of WebLogic Server System Administration

Table 4-1 lists the config.xml file parameters that affect server performance.

Table 4-1 Attributes Console For

Performance-Related Field information
config.xml Elements

Element
Server NativeIOEnabled Native IO See Using
Enabled WebLogic
Server "Native
IO"
Performance
Packs.
ExecuteQueue ThreadCount Thread See Tuning the
Count Default
Execute Queue
Threads.
ExecuteQueue QueueLength Queue See Tuning
Length Execute
 Queues for
QueueLengthThresholdPercent Queue Overflow
Length Conditions.
ThreadsIncrease
Threshold
ThreadsMaximum
Percent

Thread Priority Threads

Increase

Threads
Maximum

Thread
Priority
Server StuckThreadMaxTime Stuck See Tuning the
Thread Execute
StuckThreadTimerInterval
Max Time Thread
Detection
Stuck Behavior.
Thread
Timer
Interval
Server ThreadPoolPercentSocketReaders Socket See Allocating
Readers Execute
Threads to Act
as Socket
Readers.
Server AcceptBacklog Accept See Tuning
Backlog Connection
Backlog
Buffering.
JDBCConnectionPool InitialCapacity Initial See How
Capacity JDBC
MaxCapacity
Connection
Max Pools Enhance
Capacity Performance.
JDBCConnectionPool StatementCacheSize Statement See Caching
Cache Size Prepared and
Callable
Statements.

Development vs. Production Mode Default Tuning Values

You can indicate whether a domain is to be used in a development environment or a

production environment. WebLogic Server uses different default values for various
services depending on the type of environment you specify.
Table 4-2 lists the performance-related configuration parameters that differ when
switching from development to production startup mode.

Table 4-2 Development and Production Development Mode Production Mode

Startup Mode Tuning Defaults Default Default

Tuning Parameter
Execute Queue: ThreadCount 15 threads 25 threads
JDBC Connection Pool: MaxCapacity 15 connections 25 connections

The tuning defaults discussed in throughout WebLogic Performance and Tuning Guide
refer to the "development mode" defaults, which is the default startup mode when
WebLogic Server is installed. For information on switching the startup mode from
development to production, see Changing the Runtime Mode in the Administration
Console Online Help.

For a complete listing of the differences between development and production startup
modes, see the "Differences Between Configuration Startup Modes" section in Creating
WebLogic Configurations Using the Configuration Wizard.

Using WebLogic Server "Native IO" Performance Packs

Benchmarks show major performance improvements when you use native performance
packs on machines that host WebLogic Server instances. Performance packs use a
platform-optimized, native socket multiplexor to improve server performance. For
example, the native socket reader multiplexor threads have their own execute queue and
do not borrow threads from the default execute queue, which frees up default execute
threads to do application work.

However, if you must use the pure-Java socket reader implementation for host machines,
you can still improve the performance of socket communication by configuring the
proper number of socket reader threads for each server instance and client machine.

Which Platforms Have Performance Packs?

To see which supported platforms currently have performance packs available:

1. Go to Supported Configurations for WebLogic Server .

2. From the list of supported configurations, click on the link for the platform that
you need.

The ensuing page contains tables of information for each supported WebLogic
Server releases (including service packs). Within each release table there is a
"Performance Pack" entry that indicates whether a performance pack is
"Included" in the release.

3. To verify performance pack information, you can either click on a specific

WebLogic Server release at the top of the page and scan the corresponding table,
 or use your browser's Edit —> Find feature to search for all instances of
"Performance Pack" on the page.

Enabling Performance Packs

The use of native performance packs are enabled by default in the config.xml shipped
with your distribution. To verify this setting in your configuration file, check that the
NativeIOEnabled attribute of the Server element is set to "true"
(NativeIOEnabled=true).

You can also use the Administration Console to verify that performance packs are
enabled:

1. Start the Administration Server if it is not already running.

2. Access the Administration Console for the domain.

3. Expand the Servers node in the left pane to display the servers configured in your
domain.

4. Click the name of the server instance that you want to configure.

5. Select the Configuration —> Tuning tab.

6. If the Enable Native IO check box is not selected, select the check box.

7. Click Apply.

8. Restart the server.

Tuning the Default Execute Queue Threads

The value of the ThreadCount attribute of an ExecuteQueue element in the config.xml

file equals the number of simultaneous operations that can be performed by applications
that use the execute queue. As work enters an instance of WebLogic Server, it is placed
in an execute queue. This work is then assigned to a thread that does the work on it.
Threads consume resources, so handle this attribute with care—you can degrade
performance by increasing the value unnecessarily.

By default, a new WebLogic Server instance is configured with a development mode

execute queue, weblogic.kernel.default, that contains 15 threads. In addition,
WebLogic Server provides two other pre-configured queues:

 weblogic.admin.HTTP—Available only on Administration Servers, this queue is

reserved for communicating with the Administration Console; you cannot
reconfigure it.
 weblogic.admin.RMI—Both Administration Servers and Managed Servers have
this queue; it is reserved for administrative traffic; you cannot reconfigure it.
Unless you configure additional execute queues, and assign applications to them, Web
applications and RMI objects use weblogic.kernel.default.

Note: If native performance packs are not being used for your platform, you may need to
tune the default number of execute queue threads and the percentage of threads that act as
socket readers to achieve optimal performance. For more information, see Allocating
Execute Threads to Act as Socket Readers.

Should You Modify the Default Thread Count?

Adding more threads to the default execute queue does not necessarily imply that you can
process more work. Even if you add more threads, you are still limited by the power of
your processor. Because threads consume memory, you can degrade performance by
increasing the value of the ThreadCount attribute unnecessarily. A high execute thread
count causes more memory to be used and increases context switching, which can
degrade performance.

The value of the ThreadCount attribute depends very much on the type of work your
application does. For example, if your client application is thin and does a lot of its work
through remote invocation, that client application will spend more time connected — and
thus will require a higher thread count — than a client application that does a lot of
client-side processing.

If you do not need to use more than 15 threads (the development default) or 25 threads
(the production default) for your work, do not change the value of this attribute. As a
general rule, if your application makes database calls that take a long time to return, you
will need more execute threads than an application that makes calls that are short and turn
over very rapidly. For the latter case, using a smaller number of execute threads could
improve performance.

Scenarios for Modifying the Default Thread Count

To determine the ideal thread count for an execute queue, monitor the queue's throughput
while all applications in the queue are operating at maximum load. Increase the number
of threads in the queue and repeat the load test until you reach the optimal throughput for
the queue. (At some point, increasing the number of threads will lead to enough context
switching that the throughput for the queue begins to decrease.)

Note: The WebLogic Server Administration Console displays the cumulative throughput
for all of a server's execute queues. To access this throughput value, follow steps 1-6 in
Modifying the Default Thread Count.

Table 4-3 shows default scenarios for adjusting available threads in relation to the
number of CPUs available in the WebLogic Server domain. These scenarios also assume
that WebLogic Server is running under maximum load, and that all thread requests are
satisfied by using the default execute queue. If you configure additional execute queues
and assign applications to specific queues, monitor results on a pool-by-pool basis.
Table 4-3 Results Do This:
Scenarios for
Modifying the
Default Thread
Count

When...
Thread Count < Your thread count is too Increase the thread count.
number of CPUs low if:

 CPU is waiting to
do work, but there
is work that could
be done.

 Cannot get 100

percent CPU
utilization rate.
Thread Count = Theoretically ideal, but Increase the thread count.
number of CPUs the CPUs are still under-
utilized.
Thread Count > Practically ideal, with a Tune the moderate number of threads and
number of CPUs moderate amount of compare performance results.
(by a moderate context switching and a
number of threads) high CPU utilization rate.
Thread Count > Too much context Reduce the number of threads so that it
number of CPUs switching, which can lead equals the number of CPUs, and then add
(by a large number to significant performance only the number of "stuck" threads that
of threads) degradation. you have determined.

Your performance may For example, if you have four processors,

increase as you decrease then four threads can be running
the number of threads. concurrently with the number of stuck
threads. So, you want the execute threads
to be 4 + the number of stuck threads.

To determine the amount of stuck threads,

see Tuning the Execute Thread Detection
Behavior.

Note: This recommendation is highly

application-dependent. For instance, the
length of time the application might block
threads can invalidate the formula.

Modifying the Default Thread Count

To modify the default execute queue thread count using the Administration Console:

1. Start the Administration Server if it is not already running.

2. Access the Administration Console for the domain.

3. Expand the Servers node in the left pane to display the servers configured in your
domain.

4. Right-click the name of the server instance that contains the execute queue you
want to configure, and then select View Execute Queues on the pop-up menu to
display a table of execute queues that can be modified.

Note: You can only modify the default execute queue for the server or a user-
defined execute queue.

5. In the Name column, click directly on the default execute queue name to display
the Configuration tab for modifying execute queues.

6. Locate the Thread Count value and increase or decrease it, as appropriate.

7. Click Apply to save your changes.

8. Reboot the selected server to enable the new execute queue settings.

Assigning Applications to Execute Queues

Although you can configure the default execute queue to supply the optimal number
threads for all WebLogic Server applications, configuring multiple execute queues can
provide additional control for key applications. By using multiple execute queues, you
can guarantee that selected applications have access to a fixed number of execute threads,
regardless of the load on WebLogic Server. See Using Execute Queues to Control Thread
Usage for more information on assigning applications to configured execute queues.

Allocating Execute Threads to Act as Socket Readers

For best socket performance, BEA recommends that you use the native socket reader
implementation, rather than the pure-Java implementation, on machines that host
WebLogic Server instances (see Using WebLogic Server "Native IO" Performance
Packs). However, if you must use the pure-Java socket reader implementation for host
machines, you can still improve the performance of socket communication by
configuring the proper number of execute threads to act as socket reader threads for each
server instance and client machine.

The ThreadPoolPercentSocketReaders attribute sets the maximum percentage of

execute threads that are set to read messages from a socket. The optimal value for this
attribute is application-specific. The default value is 33, and the valid range is 1-99.

Allocating execute threads to act as socket reader threads increases the speed and the
ability of the server to accept client requests. It is essential to balance the number of
execute threads that are devoted to reading messages from a socket and those threads that
perform the actual execution of tasks in the server.

Setting the Number of Socket Reader Threads For a Server Instance

To use the Administration Console to set the maximum percentage of execute threads
that read messages from a socket:

1. Start the Administration Server if it is not already running.

2. Access the Administration Console for the domain.

3. Expand the Servers node in the left pane to display the servers configured in your
domain.

4. Click the name of the server that you want to configure.

5. Select the Configuration —> Tuning tab.

6. Edit the percentage of Java reader threads in the Socket Readers attribute field.
The number of Java socket readers is computed as a percentage of the number of
total execute threads (as shown in the Thread Count field for the Execute Queue).

7. Apply the changes.

Setting the Number of Socket Reader Threads on Client Machines

On client machines, you can configure the number of available socket reader threads in
the JVM that runs the client. Specify the socket readers by defining the following
parameters in the java command line for the client:

-Dweblogic.ThreadPoolSize=value
-Dweblogic.ThreadPoolPercentSocketReaders=value

Tuning Execute Queues for Overflow Conditions

You can configure WebLogic Server to detect and optionally address potential overflow
conditions in the default execute queue or any user-defined execute queue. WebLogic
Server considers a queue to have a possible overflow condition when its current size
reaches a user-defined percentage of its maximum size. When this threshold is reached,
the server changes its health state to "warning" and can optionally allocate additional
threads to perform the outstanding work in the queue, thereby reducing its size.

To automatically detect and address overflow conditions in a queue, you configure the
following items:

 The threshold at which the server indicates an overflow condition. This value is
set as a percentage of the configured size of the execute queue (the QueueLength
value).
  The number of threads to add to the execute queue when an overflow condition is
detected. These additional threads work to reduce the size of the queue to its
normal operating size.
 The maximum number of threads available to the queue. In particular, setting the
maximum number of threads prevents the server from assigning an overly high
thread count in response to overload conditions.

To tune an execute queue using the WebLogic Server Administration Console:

1. Start the Administration Server if it is not already running.

2. Access the Administration Console for the domain.

3. Expand the Servers node in the left pane to display the servers configured in your
domain.

4. Right-click the name of the server instance that contains the execute queue you
want to configure, and then select View Execute Queues from the pop-up menu to
display a table of execute queues that can be modified.

Note: You can only modify the default execute queue for the server or a user-
defined execute queue.

5. In the Name column, directly click the default execute queue name (or the user-
defined execute queue) that you want to configure.

6. On the execute queue Configuration tab, specify how the server instance should
detect an overflow condition for the selected queue by modifying the following
attributes:
• Queue Length: Specifies the maximum number of simultaneous requests
that the server can hold in the queue. The default of 65536 requests
represents a very large number of requests; outstanding requests in the
queue should rarely, if ever reach this maximum value. Always leave the
Queue Length at the default value of 65536 entries.
• Queue Length Threshold Percent: The percentage (from 1-99) of the
Queue Length size that can be reached before the server indicates an
overflow condition for the queue. All actual queue length sizes below the
threshold percentage are considered normal; sizes above the threshold
percentage indicate an overflow. By default, the Queue Length Threshold
Percent is set to 90 percent.
• Thread Priority: The priority of the threads associated with the queue.
By default, the Thread Priority is set to 5.

7. To specify how this server should address an overflow condition for the selected
queue, modify the following attribute:
• Threads Increase: The number of threads WebLogic Server should add
to this execute queue when it detects an overflow condition. If you specify
zero threads (the default), the server changes its health state to "warning"
in response to an overflow condition in the execute queue, but it does not
allocate additional threads to reduce the workload.
 8. To limit the maximum number of threads that can be added to the selected queue,
modify the following attribute:
• Threads Maximum: The maximum number of threads that this execute
queue can have; this value prevents WebLogic Server from creating an
overly high thread count in the queue in response to continual overflow
conditions. By default, Threads Maximum is set to 400.

9. Click Apply to save your changes.

10. Reboot the selected server to enable the new execute queue settings.

Tuning the Execute Thread Detection Behavior

WebLogic Server automatically detects when a thread in an execute queue becomes

"stuck." Because a stuck thread cannot complete its current work or accept new work, the
server logs a message each time it diagnoses a stuck thread. If all threads in an execute
queue become stuck, the server changes its health state to either "warning" or "critical"
depending on the execute queue:

 If all threads in the default queue become stuck, the server changes its health state
to "critical." (You can set up the Node Manager application to automatically shut
down and restart servers in the critical health state. For more information, see
"Node Manager Capabilities" in Configuring and Managing WebLogic Server.)
 If all threads in weblogic.admin.HTTP, weblogic.admin.RMI, or a user-defined
execute queue become stuck, the server changes its health state to "warning."

WebLogic Server diagnoses a thread as stuck if it is continually working (not idle) for a
set period of time. You can tune a server's thread detection behavior by changing the
length of time before a thread is diagnosed as stuck, and by changing the frequency with
which the server checks for stuck threads.

Note: Although you can change the criteria WebLogic Server uses to determine whether
a thread is stuck, you cannot change the default behavior of setting the "warning" and
"critical" health states when all threads in a particular execute queue become stuck. For
more information, see Overview of WebLogic Logging Services.

To configure WebLogic Server stuck thread detection behavior:

1. Start the Administration Server if it is not already running.

2. Access the Administration Console for the domain.

3. Expand the Servers node in the left pane to display the servers configured in your
domain.

4. Click the name of the server instance that you want to modify for improved stuck
thread detection.

Note: You configure stuck thread detection parameters on a per-server basis,

rather than on a per-execute queue basis.
 5. Select the Configuration —> Tuning tab in the right pane.

6. Modify the following attributes as necessary to tune thread detection behavior for
the server:
• Stuck Thread Max Time: Enter the number of seconds, that a thread
must be continually working before this server diagnoses the thread as
being stuck. By default, WebLogic Server considers a thread to be "stuck"
after 600 seconds of continuous use.
• Stuck Thread Timer Interval: Enter the number of seconds, after
which WebLogic Server periodically scans threads to see if they have
been continually working for the length of time specified by Stuck
Thread Max Time. By default, WebLogic Server sets this interval to 600
seconds.

7. Click Apply to save your changes.

8. Reboot the server to use the new settings.

Tuning Connection Backlog Buffering

Use the AcceptBacklog attribute of the Server element in the config.xml file to set the
number of connection requests the WebLogic Server instance will accept before refusing
additional requests. The AcceptBacklog attribute specifies how many Transmission
Control Protocol (TCP) connections can be buffered in a wait queue. This fixed-size
queue is populated with requests for connections that the TCP stack has received, but the
application has not accepted yet. The default value is 50 and the maximum value is
operating system dependent.

To tune the Accept Backlog value from the Administration Console:

1. Start the Administration Server if it is not already running.

2. Access the Administration Console for the domain.

3. Expand the Servers node in the left pane to display the servers configured in your
domain.

4. Click the name of the server instance that you want to configure.

5. Select the Configuration —> Tuning tab.

6. Modify the default Accept Backlog value as necessary to tune how many TCP
connections can be buffered in a wait queue:
• During operations, if many connections are dropped or refused at the
client, and no other error messages are on the server, the Accept Backlog
value might be set too low.
• If you are getting "connection refused" messages when you try to access
WebLogic Server, raise the Accept Backlog value from the default by 25
percent. Continue increasing the value by 25 percent until the messages
cease to appear.
 7. Click Apply to save your changes.

How JDBC Connection Pools Enhance Performance

Establishing a JDBC connection with a DBMS can be very slow. If your application
requires database connections that are repeatedly opened and closed, this can become a
significant performance issue. WebLogic connection pools offer an efficient solution to
the problem.

When WebLogic Server starts, connections from the connection pools are opened and are
available to all clients. When a client closes a connection from a connection pool, the
connection is returned to the pool and becomes available for other clients; the connection
itself is not closed. There is little cost to opening and closing pool connections.

How many connections should you create in the pool? A connection pool can grow and
shrink according to configured parameters, between a minimum and a maximum number
of connections. The best performance occurs when the connection pool has as many
connections as there are concurrent client sessions.

In addition to the following subsections, see "Performance Tuning Your JDBC

Application" in Programming WebLogic JDBC.

Tuning JDBC Connection Pool Initial Capacity

The InitialCapacity attribute of the JDBCConnectionPool element enables you to set

the number of physical database connections to create when configuring the pool. If the
server cannot create this number of connections, the creation of this connection pool will
fail.

During development, it may be convenient to set the value of the InitialCapacity

attribute to a low number to help the server start up faster. In production systems,
consider setting the InitialCapacity value equal to the MaxCapacity attribute's default
production mode setting of 25. This way, all database connections are acquired during
server start-up. And if you need to tune the MaxCapacity value, make sure to set the
InitialCapacity so that it equals the MaxCapacity value.

If InitialCapacity is less than MaxCapacity, the server needs to create additional

database connections when its load is increased. When the server is under load, all
resources should be working to complete requests as fast as possible, rather than creating
new database connections.

Tuning JDBC Connection Pool Maximum Capacity

The MaxCapacity attribute of the JDBCConnectionPool element allows you to set the
maximum number of physical database connections that a connection pool can contain.
Different JDBC drivers and database servers might limit the number of possible physical
connections.

The default settings for development and production mode are equal to the default
number of execute threads: 15 for development mode; 25 for production mode. However,
in production, it is advisable that the number of connections in the pool equal the number
of concurrent client sessions that require JDBC connections. The pool capacity is
independent of the number of execute threads in the server. There may be many more
ongoing user sessions than there are execute threads.

Caching Prepared and Callable Statements

When you use a prepared statement or callable statement in an application or EJB, there
is considerable processing overhead for the communication between the application
server and the database server and on the database server itself. To minimize the
processing costs, WebLogic Server can cache prepared and callable statements used in
your applications. When an application or EJB calls any of the statements stored in the
cache, WebLogic Server reuses the statement stored in the cache. Reusing prepared and
callable statements reduces CPU usage on the database server, improving performance
for the current statement and leaving CPU cycles for other tasks. For more details, see
"Increasing Performance with the Statement Cache" in the Administration Console
Online Help.

Using the statement cache can dramatically increase performance, but you must consider
its limitations before you decide to use it. For more details, see "Usage Restrictions for
the Statement Cache" in the Administration Console Online Help.

Setting Your Java Compiler

The standard Java compiler for compiling JSP servlets is javac. You can improve
performance significantly by setting your server's java compiler to sj or jikes instead of
javac. The following sections discuss this procedure and other compiler considerations.

Changing Compilers in the Administration Console

To change your compiler in the Administration Console:

1. Start the Administration Server if it is not already running.

2. Access the Administration Console for the domain.

3. Expand the Servers node in the left pane to display the servers configured in your
domain.

4. Click the name of the server instance that you want to configure.

5. Select the Configuration —> General tab and enter the full path of the compiler in
the Java Compiler field. For example:

c:\visualcafe31\bin\sj.exe

6. Click Show on the Advanced Options bar to display additional attributes.

7. Enter the full path to the JRE rt.jar library in the Append to the Classpath field.
For example:
 BEA_HOME\jdk141_02\jre\lib\rt.jar

8. Click Apply.

9. Restart your server for the new Java Compiler and Append to Classpath values to
take effect.

Setting Your Compiler in weblogic.xml

In the weblogic.xml file, the jsp-descriptor element defines parameter names and
values for servlet JSPs.

 Use the compileCommand parameter to specify the Java compiler for compiling
the generated JSP servlets.
 Use the precompile parameter to configure WebLogic Server to precompile your
JSPs when WebLogic Server starts up.

For more information about setting your server's java compiler in the weblogic.xml file,
see the jsp-descriptor element.

Compiling EJB Container Classes

Use the weblogic.appc utility to compile EJB 2.0 and 1.1 container classes. If you
compile Jar files for deployment into the EJB container, you must use weblogic.appc
to generate the container classes. By default, ejbc uses the javac compiler. For faster
performance, specify a different compiler (such as Symantec sj) using the -compiler
flag.

For more information, see "Implementing EJBs" in Programming WebLogic Enterpise

JavaBeans.

Compiling on UNIX

If you receive the following error message received when compiling JSP files on a UNIX
machine:

failed: java.io.IOException: Not enough space

Try any or all of the following solutions:

 Add more RAM if you have only 256 MB.

 Raise the file descriptor limit, for example:

set rlim_fd_max = 4096

set rlim_fd_cur = 1024

 Use the -native flag to use native threads when starting the JVM.
Using WebLogic Server Clusters to Improve Performance

A WebLogic Server cluster is a group of WebLogic Servers instances that together

provide fail-over and replicated services to support scalable high-availability operations
for clients within a domain. A cluster appears to its clients as a single server but is in fact
a group of servers acting as one to provide increased scalability and reliability.

A domain can include multiple WebLogic Server clusters and non-clustered WebLogic
Server instances. Clustered WebLogic Server instances within a domain behave similarly
to non-clustered instances, except that they provide failover and load balancing. The
Administration Server for the domain manages all the configuration parameters for the
clustered and non-clustered instances.

For more information about clusters, see "Introduction to WebLogic Server Clustering".

Scalability and High Availability

Scalability is the ability of a system to grow in one or more dimensions as more resources
are added to the system. Typically, these dimensions include (among other things), the
number of concurrent users that can be supported and the number of transactions that can
be processed in a given unit of time.

Given a well-designed application, it is entirely possible to increase performance by

simply adding more resources. To increase the load handling capabilities of WebLogic
Server, add another WebLogic Server instance to your cluster—without changing your
application. Clusters provide two key benefits that are not provided by a single server:
scalability and availability.

WebLogic Server clusters bring scalability and high-availability to J2EE applications in a

way that is transparent to application developers. Scalability expands the capacity of the
middle tier beyond that of a single WebLogic Server or a single computer. The only
limitation on cluster membership is that all WebLogic Servers must be able to
communicate by IP multicast. New WebLogic Servers can be added to a cluster
dynamically to increase capacity.

A WebLogic Server cluster guarantees high-availability by using the redundancy of

multiple servers to insulate clients from failures. The same service can be provided on
multiple servers in a cluster. If one server fails, another can take over. The ability to have
a functioning server take over from a failed server increases the availability of the
application to clients.

Caution: Provided that you have resolved all application and environment bottleneck
issues, adding additional servers to a cluster should provide linear scalability. When
doing benchmark or initial configuration test runs, isolate issues in a single server
environment before moving to a clustered environment.
How to Ensure Scalability for WebLogic Clusters

In general, any operation that requires communication between the servers in a cluster is
a potential scalability hindrance. The following sections provide information on issues
that impact the ability to linearly scale clustered WebLogic servers:

 Database Bottlenecks
 Session Replication
 Invalidation of Entity EJBs
 Invalidation of HTTP sessions
 JNDI Binding, Unbinding and Rebinding

Database Bottlenecks

In many cases where a cluster of WebLogic servers fails to scale, the database is the
bottleneck. In such situations, the only solutions are to tune the database or reduce load
on the database by exploring other options. See JDBC Application Tuning.

Session Replication

User session data can be stored in two standard ways in a J2EE application: stateful
session EJBs or HTTP sessions. By themselves, they are rarely a impact cluster
scalability. However, when coupled with a session replication mechanism required to
provide high-availability, bottlenecks are introduced. If a J2EE application has Web and
EJB components, you should store user session data in HTTP sessions rather than stateful
session EJBs as HTTP session management provides more replication options than
stateful session EJBs. See Managing Sessions.

Invalidation of Entity EJBs

This applies to entity EJBs that use a concurrency strategy of Optimistic or ReadOnly
with a read-write pattern.

Optimistic—When an Optimistic concurrency bean is updated, the EJB container

sends a multicast message to other cluster members to invalidate their local copies of the
bean. This is done to avoid optimistic concurrency exceptions being thrown by the other
servers and hence the need to retry transactions. If updates to the EJBs are frequent, the
work done by the servers to invalidate each other's local caches become a serious
bottleneck.

ReadOnly with a read-write pattern—In this pattern, persistent data that would otherwise
be represented by a single EJB are actually represented by two EJBs: one read-only and
the other updateable. When the state of the updateable bean changes, the container
automatically invalidates corresponding read-only EJB instance. If updates to the EJBs
are frequent, the work done by the servers to invalidate the read-only EJBs becomes a
serious bottleneck.
Invalidation of HTTP sessions

Similar to Invalidation of Entity EJBs, HTTP sessions can also be invalidated. This is not
as expensive as entity EJB invalidation, since only the session data stored in the
secondary server needs to be invalidated. BEA advises users to not invalidate sessions
unless absolutely required.

JNDI Binding, Unbinding and Rebinding

In general, JNDI binds, unbinds and rebinds are expensive operations. However, these
operations become a bigger bottleneck in clustered environments because JNDI tree
changes have to be propagated to all members of a cluster. If such operations are
performed too frequently, they can reduce cluster scalability significantly.

Performance Considerations When Running Multiple Server Instances on

Multi-CPU Machines

With multi-processor machines, additional consideration must be given to the ratio of the
number of available CPUs to clustered WebLogic Server instances. Because WebLogic
Server has no built-in limit to the number of server instances that reside in a cluster,
large, multi-processor servers, such as Sun Microsystems' Sun Enterprise 10000, can
potentially host very large clusters or multiple clusters.

In order to determine the optimal ratio of CPUs to WebLogic server instances, you must
first ensure that an application is truly CPU-bound, rather than network or disk I/O-
bound. Use the following steps to determine the optional ratio of CPUs to server
instances:

1. Test your application to determine the Network Requirements.

If you discover that an application is primarily network I/O-bound, consider

measures to increase network throughput before increasing the number of
available CPUs. For truly network I/O-bound applications, installing a faster
network interface card (NIC) may increase performance more than additional
CPUs, because most CPUs would remain idle while waiting to read available
sockets.

2. Test your application to determine the Disk I/O Requirements.

If you discover that an application is primarily disk I/O-bound, consider

upgrading the number of disk spindles or individual disks and controllers before
allocating additional CPUs.

3. Begin performance tests using a ratio of one WebLogic Server instance for every
available CPU.

4. If CPU utilization is consistently at or near 100 percent, increase the ratio of

CPUs to servers by adding an additional CPU. Add additional CPUs until
utilization reaches an acceptable level. Remember, always reserve some spare
 CPU cycles on your production systems to perform any administration tasks that
may occur.

Monitoring a WebLogic Server Domain

The tool for monitoring the health and performance of your WebLogic Server domain is
the Administration Console. Using the Administration Console, you can view status and
statistics for WebLogic Server resources such as servers, HTTP, the JTA subsystem,
JNDI, security, CORBA connection pools, EJB, JDBC, and JMS.

For more details, see "Monitoring a WebLogic Server Domain in Configuring and
Managing WebLogic Server.

For example, there is a Server —> Monitoring —> Performance tab on the
Administration Console that provides performance metrics related to pending and
processed requests for the current server instance. It includes the following information:

 The number of idle threads assigned to the queue.

 The oldest pending request in the queue.
 Throughput, as measured by the number of requests already processed by the
queue.
 Queue Length, as measured by the number waiting requests in the queue.
 The amount of memory available in the JVM heap.

How to Configure Large Pages

If you use this option, you will need to configure large pages on you machine.
To do so, use one of the following procedures.

On Linux
1. Reserve memory to be used for large pages by executing the following
command:

echo nn > /proc/sys/vm/nr_hugepages

Where nn is the number of desired pages.

You should do this step as soon as possible after the machine has been
started since ongoing memory usage creates fragmentation and Linux
might be unable to allocate the number of specified pages.

Note: The following steps might need to be completed by your system

administrator, unless you have administrative privileges.
1. To enable BEA JRockit to allocate large pages, make a hugetblfs file
system available by using this command:

mount -t hugetlbfs nodev /mnt/hugepages

2. Grant the user executing the Java application read and write permission to
the file system. You can do this with either the mount command or with the
chmod and chown commands.

For a more thorough description of large pages on Linux, read the file
vm/hugetlbpage.txt available in the documentation for the Linux kernel.
Setting Up WebLogic Server for HTTP Tunneling
HTTP tunneling provides a way to simulate a stateful socket connection
between WebLogic Server and a Java client when your only option is to use the
HTTP protocol. It is generally used to tunnel through an HTTP port in a security
firewall. HTTP is a stateless protocol, but WebLogic Server provides tunneling
functionality to make the connection appear to be a regular T3Connection.
However, you can expect some performance loss in comparison to a normal
socket connection.

Configuring the HTTP Tunneling Connection

Under the HTTP protocol, a client may only make a request, and then accept a
reply from a server. The server may not voluntarily communicate with the
client, and the protocol is stateless, meaning that a continuous two-way
connection is not possible.
WebLogic HTTP tunneling simulates a T3Connection via the HTTP protocol,
overcoming these limitations. There are two attributes that you can configure
in the Administration Console to tune a tunneled connection for performance. It
is advised that you leave them at their default settings unless you experience
connection problems. These properties are used by the server to determine
whether the client connection is still valid, or whether the client is still alive.
Enable Tunneling

Enables or disables HTTP tunneling. HTTP tunneling is disabled by default.

Note that the server must also support both the HTTP and T3 protocols in
order to use HTTP tunneling.
Tunneling Client Ping

When an HTTP tunnel connection is set up, the client automatically sends a
request to the server, so that the server may volunteer a response to the
client. The client may also include instructions in a request, but this
behavior happens regardless of whether the client application needs to
communicate with the server. If the server does not respond (as part of the
application code) to the client request within the number of seconds set in
this attribute, it does so anyway. The client accepts the response and
automatically sends another request immediately.
Default is 45 seconds; valid range is 20 to 900 seconds.
Tunneling Client Timeout

If the number of seconds set in this attribute have elapsed since the client
last sent a request to the server (in response to a reply), then the server
regards the client as dead, and terminates the HTTP tunnel connection. The
server checks the elapsed time at the interval specified by this attribute,
when it would otherwise respond to the client's request.
Default is 40 seconds; valid range is 10 to 900 seconds.

Connecting to WebLogic Server from the Client

When your client requests a connection with WebLogic Server, all you need to
do in order to use HTTP tunneling is specify the HTTP protocol in the URL. For
example:
Hashtable env = new Hashtable();
env.put(Context.PROVIDER_URL, "http://wlhost:80");
Context ctx = new InitialContext(env);
 On the client side, a special tag is appended to the http protocol, so that
WebLogic Server knows this is a tunneling connection, instead of a regular
HTTP request. Your application code does not need to do any extra work to
make this happen.
The client must specify the port in the URL, even if the port is 80. You can set
up your WebLogic Server instance to listen for HTTP requests on any port,
although the most common choice is port 80 since requests to port 80 are
customarily allowed through a firewall.
You specify the listen port for WebLogic Server in the Administration Console
under the "Servers" node, under the "Network" tab.

Using Native I/O for Serving Static Files (Windows Only)

When running WebLogic Server on Windows NT/2000/XP you can specify that
WebLogic Server use the native operating system call TransmitFile instead of
using Java methods to serve static files such as HTML files, text files, and
image files. Using native I/O can provide performance improvements when
serving larger static files.
To use native I/O, add two parameters to the web.xml deployment descriptor
of a Web Application containing the files to be served using native I/O. The first
parameter, weblogic.http.nativeIOEnabled should be set to TRUE to enable
native I/O file serving. The second parameter,
weblogic.http.minimumNativeFileSize sets the minimum file size for using
native I/O. If the file being served is larger than this value, native I/O is used.
If you do not specify this parameter, a value of 4K is used.
Generally, native I/O provides greater performance gains when serving larger
files; however, as the load on the machine running WebLogic Server increases,
these gains diminish. You may need to experiment to find the correct value for
weblogic.http.minimumNativeFileSize.
The following example shows the complete entries that should be added to the
web.xml deployment descriptor. These entries must be placed in the web.xml
file after the <distributable> element and before <servlet> element.
<context-param>
<param-name>weblogic.http.nativeIOEnabled</param-name>
<param-value>TRUE</param-value>
</context-param>
<context-param>
<param-name>weblogic.http.minimumNativeFileSize</param-name>
<param-value>500</param-value>
</context-param>

weblogic.http.nativeIOEnabled can also be set as a context parameter in the

FileServlet.

Configure Clusters
A cluster is a group of WebLogic Server instances that work together to provide
scalability and high-availability for applications. This window is displayed only if your
domain contains at least one Managed Server.

The Configure Clusters window prompts you to configure the clusters in your domain.
This step is optional.
To configure clusters:
1. Review the current list of cluster configurations. Default values may vary,
based on the domain source you selected earlier.

Note: The wizard provides two views: a concise tabular view of all the
clusters and an individual view of each cluster, where each cluster is
represented by a tab—you switch between clusters by selecting the
corresponding tab. To toggle the display mode between table and tab formats,
click Switch Display.

2. Add or modify entries, as required by your domain, using the guidelines

provided in the following table. To delete a cluster, select the cluster in the list and
click Delete. When you finish updating your settings, click Next.

Note: If you are creating a domain that includes Service Bus functionality,
you can configure only one cluster per domain.

In this Enter a . . .
field . . .

Note: Fields marked with an asterisk are required.

Name* Valid cluster name: a string of characters that can include spaces.
The name of the cluster must be unique among all component
names within the domain.
The default value in this field is new_Cluster_n, where n specifies
a numeric value that is used to differentiate among all default
cluster names; the value of n for the first cluster is 1. The value is
incremented by 1 for each cluster that is added.

Multicast Multicast address for the cluster. This address is used by cluster
address members to communicate with each other. The default value is
239.192.0.0.
Valid multicast addresses are any valid IP addresses from
224.0.0.1 to 239.255.255.255.

Multicast Multicast port for the cluster. The multicast port is used by cluster
port members to communicate with each other. The default value is
7001.
Valid values for multicast ports are from 1 to 65534.

Cluster Cluster address that identifies the Managed Servers in the cluster.
address
A cluster address can be one of the following:
 Comma-separated list of IP addresses or DNS
names and ports, for example: dns_name:port,
dns_name:port
 DNS name that maps to multiple IP addresses
 localhost, DNS name, or IP address if the listen
address of all Managed Servers is listening to the same
 address with unique port numbers
The cluster address is used in entity and stateless EJBs to construct
the host name portion of URLs. If the cluster address is not set,
EJB handles may not work properly.

What Types of Objects Can Be Clustered?

A clustered application or application component is one that is available on multiple

WebLogic Server instances in a cluster. If an object is clustered, failover and load
balancing for that object is available. Deploy objects homogeneously—to every server
instance in your cluster—to simplify cluster administration, maintenance, and
troubleshooting.

Web applications can consist of different types of objects, including Enterprise Java
Beans (EJBs), servlets, and Java Server Pages (JSPs). Each object type has a unique set
of behaviors related to control, invocation, and how it functions within an application.
For this reason, the methods that WebLogic Server uses to support clustering—and hence
to provide load balancing and failover—can vary for different types of objects. The
following types of objects can be clustered in a WebLogic Server deployment:

 Servlets
 JSPs
 EJBs
 Remote Method Invocation (RMI) objects
 Java Messaging Service (JMS) destinations
 Java Database Connectivity (JDBC) connections

Different object types can have certain behaviors in common. When this is the case, the
clustering support and implementation considerations for those similar object types may
be same. In the sections that follow, explanations and instructions for the following types
of objects are generally combined:

 Servlets and JSPs

 EJBs and RMI objects

The sections that follow briefly describe the clustering, failover, and load balancing
support that WebLogic Server provides for different types of objects.

Servlets and JSPs

WebLogic Server provides clustering support for servlets and JSPs by replicating the
HTTP session state of clients that access clustered servlets and JSPs. WebLogic Server
can maintain HTTP session states in memory, a filesystem, or a database.
To enable automatic failover of servlets and JSPs, session state must persist in memory.
For information about how failover works for servlets and JSPs, and for related
requirements and programming considerations, see HTTP Session State Replication.

You can balance the servlet and JSP load across a cluster using a WebLogic Server proxy
plug-in or external load balancing hardware. WebLogic Server proxy plug-ins perform
round robin load balancing. External load balancers typically support a variety of session
load balancing mechanisms. For more information, see Load Balancing for Servlets and
JSPs.

EJBs and RMI Objects

Load balancing and failover for EJBs and RMI objects is handled using replica-aware
stubs, which can locate instances of the object throughout the cluster. Replica-aware
stubs are created for EJBs and RMI objects as a result of the object compilation process.
EJBs and RMI objects are deployed homogeneously—to all the server instances in the
cluster.

Failover for EJBs and RMI objects is accomplished using the object's replica-aware stub.
When a client makes a call through a replica-aware stub to a service that fails, the stub
detects the failure and retries the call on another replica. To understand failover support
for different types of objects, see Replication and Failover for EJBs and RMIs.

WebLogic Server clusters support multiple algorithms for load balancing clustered EJBs
and RMI objects: round-robin, weight-based, random, round-robin-affinity, weight-
based-affinity, and random-affinity. By default, a WebLogic Server cluster will use the
round-robin method. You can configure a cluster to use one of the other methods using
the Administration Console. The method you select is maintained within the replica-
aware stub obtained for clustered objects. For details, see Load Balancing for EJBs and
RMI Objects.

JDBC Connections

WebLogic Server allows you to cluster JDBC objects, including data sources and multi
data sources, to improve the availability of cluster-hosted applications. Each JDBC object
you configure for your cluster must exist on each managed server in the cluster—when
you configure the JDBC objects, target them to the cluster.

 Data Sources—In a cluster, external clients must obtain connections

through a JDBC data source on the JNDI tree. The data source uses the WebLogic
Server RMI driver to acquire a connection. The cluster-aware nature of WebLogic
data sources in external client applications allows a client to request another
connection if the server instance hosting the previous connection fails. Although
not strictly required, BEA recommends that server-side clients also obtain
connections via a data source on the JNDI tree.
 Multi data sources—Multi data sources are an abstraction around a group of
data sources that provides load balancing or failover processing between the data
sources associated with the multi data source. Multi data sources are bound to the
JNDI tree or local application context just like data sources are bound to the JNDI
tree. Applications lookup a multi data source on the JNDI tree just like they do for
data sources, and then request a database connection. The multi data source
determines which data source to use to satisfy the request depending on the
algorithm selected in the multi data source configuration: load balancing or
failover.

For more information about JDBC, see Configuring WebLogic JDBC Resources in the
Configuring and Managing WebLogic JDBC.

Getting Connections with Clustered JDBC

To ensure that any JDBC request can be handled equivalently by any cluster member,
each managed server in the cluster must have similarly named/defined data sources, if
applicable, multi data sources. To achieve this result, data sources and multi data sources
should be targeted to the cluster so they are cluster-aware and, if intended for use in
external clients, their connections can be to any cluster members.

 External Clients Connections—External clients that require a database

connection perform a JNDI lookup and obtain a replica-aware stub for the data
source. The stub for the data source contains a list of the server instances that
host the data source—which should be all of the Managed Servers in the cluster.
Replica-aware stubs contain load balancing logic for distributing the load among
host server instances.
 Server-Side Client Connections—For server-side use, connection requests
will be handled by the local instance of the data source or multi data source. A
server-side data source will not go to another cluster member for its JDBC
connections. The connection is pinned to the local server instance for the duration
of the database transaction, and as long as the application code retains it (until the
connection is closed).

Failover and Load Balancing for JDBC Connections

Clustering your JDBC objects does not enable failover of connections, but it can ease the
process of reconnecting when a connection fails. In replicated database environments,
multi data sources may be clustered to support database failover, and optionally, load
balancing of connections. See the following topics for more information:

 To understand the behavior of clustered JDBC objects when failures occur,

see Failover and JDBC Connections.
 To learn more about how clustered multi data sources enable load
balancing of connections, see Load Balancing for JDBC Connections.
 For instructions on configuring clustered JDBC objects, see Configure
Clustered JDBC.

JMS and Clustering

The WebLogic Java Messaging Service (JMS) architecture implements clustering of

multiple JMS servers by supporting cluster-wide, transparent access to destinations from
any WebLogic Server server instance in the cluster. Although WebLogic Server supports
distributing JMS destinations and connection factories throughout a cluster, the same
JMS topic or queue is still managed separately by each WebLogic Server instance in the
cluster.

Load balancing is supported for JMS. To enable load balancing, you must configure
targets for JMS servers. For more information about load balancing and JMS
components, see Load Balancing for JMS. For instructions on setting up clustered JMS,
see Configure Migratable Targets for Pinned Services and Deploying, Activating, and
Migrating Migratable Services.

What Types of Objects Cannot Be Clustered?

The following APIs and internal services cannot be clustered in WebLogic Server:

 File services including file shares

 Time services

You can still use these services on individual WebLogic Server instances in a cluster.
However, the services do not make use of load balancing or failover features.

WebLogic Server Communication in a Cluster

WebLogic Server instances in a cluster communicate with one another using two basic
network technologies:

• IP multicast, which server instances use to broadcast availability

of services and heartbeats that indicate continued availability.
• IP sockets, which are the conduits for peer-to-peer communication
between clustered server instances.

The way in which WebLogic Server uses IP multicast and socket communication affects
the way you configure your cluster.

One-to-Many Communication Using IP Multicast

IP multicast is a simple broadcast technology that enables multiple applications to

"subscribe" to a given IP address and port number and listen for messages. A multicast
address is an IP address in the range from 224.0.0.0 to 239.255.255.255.

Note: The default multicast value used by WebLogic Server is 239.192.0.0. You should
not use any multicast address within the range x.0.0.1.

IP multicast broadcasts messages to applications, but it does not guarantee that messages
are actually received. If an application's local multicast buffer is full, new multicast
messages cannot be written to the buffer and the application is not notified when
messages are "dropped." Because of this limitation, WebLogic Server instances allow for
the possibility that they may occasionally miss messages that were broadcast over IP
multicast.

WebLogic Server uses IP multicast for all one-to-many communications among server
instances in a cluster. This communication includes:
 Cluster-wide JNDI updates—Each WebLogic Server instance in a cluster
uses multicast to announce the availability of clustered objects that are deployed
or removed locally. Each server instance in the cluster monitors these
announcements and updates its local JNDI tree to reflect current deployments of
clustered objects. For more details, see Cluster-Wide JNDI Naming Service.
 Cluster heartbeats— Each WebLogic Server instance in a cluster uses
multicast to broadcast regular "heartbeat" messages that advertise its availability.
By monitoring heartbeat messages, server instances in a cluster determine when a
server instance has failed. (Clustered server instances also monitor IP sockets as a
more immediate method of determining when a server instance has failed.)

Multicast and Cluster Configuration

Because multicast communications control critical functions related to detecting failures
and maintaining the cluster-wide JNDI tree (described in Cluster-Wide JNDI Naming
Service) it is important that neither the cluster configuration nor the network topology
interfere with multicast communications. The sections that follow provide guidelines for
avoiding problems with multicast communication in a cluster.

If Your Cluster Spans Multiple Subnets in a WAN

In many deployments, clustered server instances reside within a single subnet, ensuring
multicast messages are reliably transmitted. However, you may want to distribute a
WebLogic Server cluster across multiple subnets in a Wide Area Network (WAN) to
increase redundancy, or to distribute clustered server instances over a larger geographical
area.

If you choose to distribute a cluster over a WAN (or across multiple subnets), plan and
configure your network topology to ensure that multicast messages are reliably
transmitted to all server instances in the cluster. Specifically, your network must meet the
following requirements:

 Full support of IP multicast packet propagation. In other words, all routers

and other tunneling technologies must be configured to propagate multicast
messages to clustered server instances.
 Network latency low enough to ensure that most multicast messages reach
their final destination in 200 to 300 milliseconds.
 Multicast Time-To-Live (TTL) value for the cluster high enough to ensure
that routers do not discard multicast packets before they reach their final
destination. For instructions on setting the Multicast TTL parameter, see Configure
Multicast Time-To-Live (TTL).

Note: Distributing a WebLogic Server cluster over a WAN may require network facilities
in addition to the multicast requirements described above. For example, you may want to
configure load balancing hardware to ensure that client requests are directed to server
instances in the most efficient manner (to avoid unnecessary network hops).

Firewalls Can Break Multicast Communication

Although it may be possible to tunnel multicast traffic through a firewall, this practice is
not recommended for WebLogic Server clusters. Treat each WebLogic Server cluster as a
logical unit that provides one or more distinct services to clients of a Web application. Do
not split this logical unit between different security zones. Furthermore, any technologies
that potentially delay or interrupt IP traffic can disrupt a WebLogic Server cluster by
generating false failures due to missed heartbeats.

Do Not Share the Cluster Multicast Address with Other Applications

Although multiple WebLogic Server clusters can share a single IP multicast address and
port, other applications should not broadcast or subscribe to the multicast address and
port used by your cluster or clusters. That is, if the machine or machines that host your
cluster also host other applications that use multicast communications, make sure that
those applications use a different multicast address and port than the cluster does.

Sharing the cluster multicast address with other applications forces clustered server
instances to process unnecessary messages, introducing overhead. Sharing a multicast
address may also overload the IP multicast buffer and delay transmission of WebLogic
Server heartbeat messages. Such delays can result in a WebLogic Server instance being
marked as failed, simply because its heartbeat messages were not received in a timely
manner.

For these reasons, assign a dedicated multicast address for use by WebLogic Server
clusters, and ensure that the address can support the broadcast traffic of all clusters that
use the address.

If Multicast Storms Occur

If server instances in a cluster do not process incoming messages on a timely basis,

increased network traffic, including NAK messages and heartbeat re-transmissions, can
result. The repeated transmission of multicast packets on a network is referred to as a
multicast storm, and can stress the network and attached stations, potentially causing end-
stations to hang or fail. Increasing the size of the multicast buffers can improve the rate at
which announcements are transmitted and received, and prevent multicast storms. See
Configure Multicast Buffer Size.

Peer-to-Peer Communication Using IP Sockets

IP sockets provide a simple, high-performance mechanism for transferring messages and

data between two applications. Clustered WebLogic Server instances use IP sockets for:

 Accessing non-clustered objects deployed to another clustered server

instance on a different machine.
 Replicating HTTP session states and stateful session EJB states between a
primary and secondary server instance.
 Accessing clustered objects that reside on a remote server instance. (This
generally occurs only in a multi-tier cluster architecture, such as the one described
in Recommended Multi-Tier Architecture.)

Note: The use of IP sockets in WebLogic Server extends beyond the cluster scenario—all
RMI communication takes place using sockets, for example, when a remote Java client
application accesses a remote object.
Proper socket configuration is crucial to the performance of a WebLogic Server cluster.
Two factors determine the efficiency of socket communications in WebLogic Server:

 Whether the server instance's host system uses a native or a pure-Java

socket reader implementation.
 For systems that use pure-Java socket readers, whether the server instance
is configured to use enough socket reader threads.

Package Applications for Deployment

You must package applications before you deploy them to WebLogic Server. For more
information, see the packaging topic in Deploying the Application in Developing
Applications for WebLogic Server.

Deploy Applications

Clustered objects in WebLogic Server should be deployed homogeneously. To ensure

homogeneous deployment, when you select a target use the cluster name, rather than
individual WebLogic Server instances in the cluster.

The console automates deploying replica-aware objects to clusters. When you deploy an
application or object to a cluster, the console automatically deploys it to all members of
the cluster (whether they are local to the Administration Server machine or they reside on
remote machines.) For a discussion of application deployment in clustered environments
see Methods of Configuring Clusters. For a broad discussion of deployment topics, see
Deploying WebLogic Server Applications.

Note: All server instances in your cluster should be running when you deploy
applications to the cluster using the Administration Console

Deploying to a Single Server Instance (Pinned Deployment)

Deploying a application to a server instance, rather than the all cluster members is called
a pinned deployment. Although a pinned deployment targets a specific server instance, all
server instances in the cluster must be running during the deployment process.

You can perform a pinned deployment using the Administration Console or from the
command line, using weblogic.Deployer.

Pinned Deployment from the Command Line

From a command shell, use the following syntax to target a server instance:

java weblogic.Deployer -activate -name ArchivedEarJar -source

C:/MyApps/JarEar.ear -target server1

Cancelling Cluster Deployments

You can cancel a deployment using the Administration Console or from the command
line, using weblogic.Deployer.

Cancel Deployment from the Command Line

From a command shell, use the following syntax to cancel the deployment task ID:

java weblogic.Deployer -adminurl http://admin:7001 -cancel -id tag

Cancel Deployment Using the Administration Console

In the Administration Console, open the Tasks node to view and to cancel any current
deployment tasks.

Viewing Deployed Applications

To view a deployed application in the Administration Console:

1. In the Console, click the Deployments node.

2. View a list of deployed applications in the table displayed in the Console.

Undeploying Deployed Applications

To undeploy a deployed application from the WebLogic Server Administration Console:

1. In the Console, click Deployments.

2. In the displayed table, check the checkbox to the left of the application you
want to undeploy.
3. If you have not already done so, click the Lock & Edit button in the top left
corner of the console.
4. Click Stop.
5. Select when you want the application to stop (undeploy).
6. Click Yes.
7. Click the Activate Changes button in the top left corner of the console to
activate your changes.

Understanding Cluster Configuration

This following sections explain how the information that defines the configuration of a
cluster is stored and maintained, and the methods you can use to accomplish
configuration tasks:

 Cluster Configuration and config.xml

 Role of the Administration Server
 How Dynamic Configuration Works
 Methods of Configuring Clusters
Note: Much of the information in this section also pertains to the process of configuring a
WebLogic domain in which the server instances are not clustered.

Cluster Configuration and config.xml

The config.xml file is an XML document that describes the configuration of a

WebLogic Server domain. config.xml consists of a series of XML elements. The
Domain element is the top-level element, and all elements in the Domain descend from
the Domain element. The Domain element includes child elements, such as the Server,
Cluster, and Application elements. These child elements may have children of their own.
For example, the Server element includes the child elements WebServer, SSL and Log.
The Application element includes the child elements EJBComponent and
WebAppComponent.

Each element has one or more configurable attributes. An attribute defined in

config.dtd has a corresponding attribute in the configuration API. For example, the
Server element has a ListenPort attribute, and likewise, the
weblogic.management.configuration.ServerMBean has a ListenPort attribute.
Configurable attributes are readable and writable, that is, ServerMBean has a
getListenPort and a setListenPort method.

To learn more about config.xml, see Domain Configuration Files in Understanding

Domain Configuration.

Role of the Administration Server

The Administration Server is the WebLogic Server instance that configures and manages
the WebLogic Server instances in its domain.

A domain can include multiple WebLogic Server clusters and non-clustered WebLogic
Server instances. Strictly speaking, a domain could consist of only one WebLogic Server
instance—however, in that case that sole server instance would be an Administration
Server, because each domain must have exactly one Administration Server.

There are a variety of ways to invoke the services of the Administration Server to
accomplish configuration tasks, as described in Methods of Configuring Clusters.
Whichever method is used, the Administration Server for a cluster must be running when
you modify the configuration.

When the Administration Server starts, it loads the config.xml for the domain. It looks
for config.xml in the directory:

BEA_HOME/user_projects/domains/<domain_name>/config

where domain_name is a domain-specific directory, with the same name as the domain.

Each time the Administration Server starts successfully, a backup configuration file
named config.xml.booted is created in the domain directory. In the unlikely event that
the config.xml file should be corrupted during the lifetime of the server instance, it is
possible to revert to this previous configuration.
The following figure shows a typical production environment that contains an
Administration Server and multiple WebLogic Servers instances. When you start the
server instances in such a domain, the Administration Server is started first. As each
additional server instance is started, it contacts the Administration Server for its
configuration information. In this way, the Administration Server operates as the central
control entity for the configuration of the entire domain.

Figure 4-1 WebLogic Server Configuration

What Happens if the Administration Server Fails?

The failure of an Administration Server for a domain does not affect the operation of
Managed Servers in the domain. If an Administration Server for a domain becomes
unavailable while the server instances it manages—clustered or otherwise—are up and
running, those Managed Servers continue to run. If the domain contains clustered server
instances, the load balancing and failover capabilities supported by the domain
configuration remain available, even if the Administration Server fails.

Note: If an Administration Server fails because of a hardware or software failure on its

host machine, other server instances on the same machine may be similarly affected.
However, the failure of an Administration Server itself does not interrupt the operation of
Managed Servers in the domain.

For instructions on re-starting an Administration Server, see Avoiding and Recovering

From Server Failure in Managing Server Startup and Shutdown.

How Dynamic Configuration Works

WebLogic Server allows you to change the configuration attributes of domain resources
dynamically—while server instances are running. In most cases you do not need to restart
the server instance for your changes to take effect. When an attribute is reconfigured, the
new value is immediately reflected in both the current run-time value of the attribute and
the persistent value stored in config.xml.

Not all configuration changes are applied dynamically. For example, if you change a
Managed Server's ListenPort value, the new port will not be used until the next time
you start the Managed Server. The updated value is stored in config.xml, but the
runtime value is not affected.

The Administration Console validates attribute changes, checking for out-of-range errors
and data type mismatch errors, and displays an error message for erroneous entries.

Once the Administration Console has been started, if another process captures the listen
port assigned to the Administration Server, you should stop the process that captured the
port. If you are not able to remove the process that captured the listen port, edit the
config.xml file to change the ListenPort value.

Methods of Configuring Clusters

There are several methods for configuring a clusters:

 Domain Configuration Wizard

The Domain Configuration Wizard is the recommended tool for creating a

new domain or cluster. For a list of the tasks you can perform with the
wizard, see Domain Configuration Wizard Capabilities later in this section.

 WebLogic Server Administration Console

The Administration Console is a graphical user interface (GUI) to the BEA

Administration Service. It allows you to perform a variety of domain
configuration and monitoring functions. For a list of the tasks you can
perform with the console, see Administration Console Capabilities.

 WebLogic Server Application Programming Interface (API)

You can write a program to modify the configuration attributes, based on the
configuration application programming interface (API) provided with
WebLogic Server. This method is not recommended for initial cluster
implementation.
 WebLogic Scripting Tool (WLST)

The WebLogic Scripting Tool (WLST) is a command-line scripting interface

that system administrators and operators use to monitor and manage
WebLogic Server instances and domains. For more information, see
WebLogic Scripting Tool.

 Java Management Extensions (JMX)

JMX is the J2EE solution for monitoring and managing resources on a

network. BEA WebLogic Server provides a set of MBeans that you can use
to configure, monitor, and manage WebLogic Server resources through JMX.

Domain Configuration Wizard Capabilities

The Domain Configuration Wizard uses pre-configured domain templates to ease the
process of creating a domain and its server instances. Using the wizard, you can select a
domain template, and then supply key information, such as machine addresses, names,
and port numbers for the server instances you wish to created.

Note: The Domain Configuration Wizard can install the appropriate directory structure
and scripts for a domain on a Managed Server that is running on a remote machine from
the Administration Server. This is helpful if you need to use a Managed Server as a
backup Administration Server for a domain.

The wizard prompts you to select one of four typical domain configurations:

 Single Server—domain with a single WebLogic Server instance.

 Administration Server with Managed Servers—domain with an
Administration Server, and one or more Managed Servers that are not clustered.
 Administration Server with clustered Managed Servers—domain with an
Administration Server, and one or more Managed Servers that are clustered.
 Managed Server (Owning Administrative Configuration)

After you select the desired configuration type, the wizard prompts you to provide
relevant details about the domain and its server instances.

For information on how to use the Domain Configuration Wizard, see Creating
WebLogic Domains Using the Configuration Wizard.

Administration Console Capabilities

These sections in Administration Console Online Help list and describe the cluster-
related configuration tasks you can perform using the WebLogic Server Administration
Console.

 Servers
 Clusters
 Deploying Applications and Modules
 Monitoring a Server
 Monitoring a Cluster"

Load Balancing in a Cluster

This section describes the load balancing support that a WebLogic Server cluster
provides for different types of objects, and related planning and configuration
considerations for architects and administrators. It contains the following information:

 Load Balancing for Servlets and JSPs

 Load Balancing for EJBs and RMI Objects
 Load Balancing for JMS
 Load Balancing for JDBC Connections

For information about replication and failover in a cluster, see Failover and Replication in
a Cluster.

Load Balancing for Servlets and JSPs

Load balancing of servlets and JSPs can be accomplished with the built-in load balancing
capabilities of a WebLogic proxy plug-in or with separate load balancing hardware.

Note: In addition to distributing HTTP traffic, external load balancers can distribute
initial context requests that come from Java clients over t3 and the default channel. See
Load Balancing for EJBs and RMI Objects for a discussion of object-level load balancing
in WebLogic Server.

Load Balancing with a Proxy Plug-in

The WebLogic proxy plug-in maintains a list of WebLogic Server instances that host a
clustered servlet or JSP, and forwards HTTP requests to those instances on a round-robin
basis. This load balancing method is described in Round Robin Load Balancing.

The plug-in also provides the logic necessary to locate the replica of a client's HTTP
session state if a WebLogic Server instance should fail.

WebLogic Server supports the following Web servers and associated proxy plug-ins:

 WebLogic Server with the HttpClusterServlet

 Netscape Enterprise Server with the Netscape (proxy) plug-in
 Apache with the Apache Server (proxy) plug-in
 Microsoft Internet Information Server with the Microsoft-IIS (proxy) plug-in

For instructions on setting up proxy plug-ins, see Configure Proxy Plug-Ins.

How Session Connection and Failover Work with a Proxy Plug-in

For a description of connection and failover for HTTP sessions in a cluster with proxy
plug-ins, see Accessing Clustered Servlets and JSPs Using a Proxy.

Load Balancing HTTP Sessions with an External Load Balancer

Clusters that utilize a hardware load balancing solution can use any load balancing
algorithm supported by the hardware. These can include advanced load-based balancing
strategies that monitor the utilization of individual machines.

Load Balancer Configuration Requirements

If you choose to use load balancing hardware instead of a proxy plug-in, it must support a
compatible passive or active cookie persistence mechanism, and SSL persistence.

 Passive Cookie Persistence

Passive cookie persistence enables WebLogic Server to write a cookie

containing session parameter information through the load balancer to the
client. For information about the session cookie and how a load balancer uses
session parameter data to maintain the relationship between the client and the
primary WebLogic Server hosting a HTTP session state, see Load Balancers
and the WebLogic Session Cookie.

 Active Cookie Persistence

Certain active cookie persistence mechanisms can be used with WebLogic

Server clusters, provided the load balancer does not modify the WebLogic
Server cookie. WebLogic Server clusters do not support active cookie
persistence mechanisms that overwrite or modify the WebLogic HTTP
session cookie. If the load balancer's active cookie persistence mechanism
works by adding its own cookie to the client session, no additional
configuration is required to use the load balancer with a WebLogic Server
cluster.

 SSL Persistence

When SSL persistence is used, the load balancer performs all encryption and
decryption of data between clients and the WebLogic Server cluster. The load
balancer then uses the plain text cookie that WebLogic Server inserts on the
client to maintain an association between the client and a particular server in
the cluster.
 Load Balancers and the WebLogic Session Cookie
A load balancer that uses passive cookie persistence can use a string in the WebLogic
session cookie to associate a client with the server hosting its primary HTTP session
state. The string uniquely identifies a server instance in the cluster. You must configure
the load balancer with the offset and length of the string constant. The correct values for
the offset and length depend on the format of the session cookie.

The format of a session cookie is:

sessionid!primary_server_id!secondary_server_id

where:

 sessionid is a randomly generated identifier of the HTTP session. The

length of the value is configured by the IDLength parameter in the <session-
descriptor> element in the weblogic.xml file for an application. By default, the
sessionid length is 52 bytes.

 primary_server_id and secondary_server_id are 10 character identifiers

of the primary and secondary hosts for the session.

Note: For sessions using non-replicated memory, cookie, JDBC, or file-based session
persistence, the secondary_server_id is not present. For sessions that use in-memory
replication, if the secondary session does not exist, the secondary_server_id is
"NONE".

For general instructions on configuring load balancers, see Configuring Load Balancers
that Support Passive Cookie Persistence. Instructions for configuring BIG-IP, see
Configuring BIG-IPTM Hardware with Clusters.

Related Programming Considerations

For programming constraints and recommendations for clustered servlets and JSPs, see
Programming Considerations for Clustered Servlets and JSPs.

How Session Connection and Failover Works with a Load

Balancer
For a description of connection and failover for HTTP sessions in a cluster with load
balancing hardware, see Accessing Clustered Servlets and JSPs with Load Balancing
Hardware.

Load Balancing for EJBs and RMI Objects

This section describes WebLogic Server load balancing algorithms for EJBs and RMI
objects.

The load balancing algorithm for an object is maintained in the replica-aware stub
obtained for a clustered object.
By default, a WebLogic Server cluster uses round-robin load balancing, described in
Round Robin Load Balancing. You can configure a different default load balancing
method for the cluster by using the Administration Console to set
weblogic.cluster.defaultLoadAlgorithm. For instructions, see Configure Load
Balancing Method for EJBs and RMIs. You can also specify the load balancing algorithm
for a specific RMI object using the -loadAlgorithm option in rmic, or with the home-
load-algorithm or stateless-bean-load-algorithm in an EJB's deployment
descriptor. A load balancing algorithm that you configure for an object overrides the
default load balancing algorithm for the cluster.

In addition to the standard load balancing algorithms, WebLogic Server supports custom
parameter-based routing. For more information, see Parameter-Based Routing for
Clustered Objects.

Round Robin Load Balancing

WebLogic Server uses the round-robin algorithm as the default load balancing strategy
for clustered object stubs when no algorithm is specified. This algorithm is supported for
RMI objects and EJBs. It is also the method used by WebLogic proxy plug-ins.

The round-robin algorithm cycles through a list of WebLogic Server instances in order.
For clustered objects, the server list consists of WebLogic Server instances that host the
clustered object. For proxy plug-ins, the list consists of all WebLogic Server instances
that host the clustered servlet or JSP.

The advantages of the round-robin algorithm are that it is simple, cheap and very
predictable. The primary disadvantage is that there is some chance of convoying.
Convoying occurs when one server is significantly slower than the others. Because
replica-aware stubs or proxy plug-ins access the servers in the same order, a slow server
can cause requests to "synchronize" on the server, then follow other servers in order for
future requests.

Note: WebLogic Server does not always load balance an object's method calls. For more
information, see Optimization for Collocated Objects.

Weight-Based Load Balancing

This algorithm applies only to EJB and RMI object clustering.

Weight-based load balancing improves on the round-robin algorithm by taking into

account a pre-assigned weight for each server. You can use the Server -> Configuration
-> Cluster tab in the Administration Console to assign each server in the cluster a
numerical weight between 1 and 100, in the Cluster Weight field. This value determines
what proportion of the load the server will bear relative to other servers. If all servers
have the same weight, they will each bear an equal proportion of the load. If one server
has weight 50 and all other servers have weight 100, the 50-weight server will bear half
as much as any other server. This algorithm makes it possible to apply the advantages of
the round-robin algorithm to clusters that are not homogeneous.
If you use the weight-based algorithm, carefully determine the relative weights to assign
to each server instance. Factors to consider include:

 The processing capacity of the server's hardware in relationship to other

servers (for example, the number and performance of CPUs dedicated to WebLogic
Server).
 The number of non-clustered ("pinned") objects each server hosts.

If you change the specified weight of a server and reboot it, the new weighting
information is propagated throughout the cluster via the replica-aware stubs. For related
information see Cluster-Wide JNDI Naming Service.

Notes: WebLogic Server does not always load balance an object's method calls. For more
information, see Optimization for Collocated Objects.

In this version of WebLogic Server, weight-based load balancing is not supported for
objects that communicate using the RMI/IIOP protocol.

Random Load Balancing

The random method of load balancing applies only to EJB and RMI object clustering.

In random load balancing, requests are routed to servers at random. Random load
balancing is recommended only for homogeneous cluster deployments, where each server
instance runs on a similarly configured machine. A random allocation of requests does
not allow for differences in processing power among the machines upon which server
instances run. If a machine hosting servers in a cluster has significantly less processing
power than other machines in the cluster, random load balancing will give the less
powerful machine as many requests as it gives more powerful machines.

Random load balancing distributes requests evenly across server instances in the cluster,
increasingly so as the cumulative number of requests increases. Over a small number of
requests the load may not be balanced exactly evenly.

Disadvantages of random load balancing include the slight processing overhead incurred
by generating a random number for each request, and the possibility that the load may not
be evenly balanced over a small number of requests.

Note: WebLogic Server does not always load balance an object's method calls. For more
information, see Optimization for Collocated Objects.

Server Affinity Load Balancing Algorithms

WebLogic Server provides three load balancing algorithms for RMI objects that provide
server affinity. Server affinity turns off load balancing for external client connections:
instead, the client considers its existing connections to WebLogic server instances when
choosing the server instance on which to access an object. If an object is configured for
server affinity, the client-side stub attempts to choose a server instance to which it is
already connected, and continues to use the same server instance for method calls. All
stubs on that client attempt to use that server instance. If the server instance becomes
unavailable, the stubs fail over, if possible, to a server instance to which the client is
already connected.

The purpose of server affinity is to minimize the number IP sockets opened between
external Java clients and server instances in a cluster. WebLogic Server accomplishes this
by causing method calls on objects to "stick" to an existing connection, instead of being
load balanced among the available server instances. With server affinity algorithms, the
less costly server-to-server connections are still load-balanced according to the
configured load balancing algorithm—load balancing is disabled only for external client
connections.

Server affinity is used in combination with one of the standard load balancing methods:
round-robin, weight-based, or random:

 round-robin-affinity—server affinity governs connections between external

Java clients and server instances; round robin load balancing is used for
connections between server instances.
 weight-based-affinity—server affinity governs connections between external
Java clients and server instances; weight-based load balancing is used for
connections between server instances.
 random-affinity—server affinity governs connections between external Java
clients and server instances; random load balancing is used for connections
between server instances.

Server Affinity and Initial Context

A client can request an initial context from a particular server instance in the cluster, or
from the cluster by specifying the cluster address in the URL. The connection process
varies, depending on how the context is obtained:

 If the initial context is requested from a specific Managed Server, the

context is obtained using a new connection to the specified server instance.
 If the initial context is requested from a the cluster, by default, context
requests are load balanced on a round-robin basis among the clustered server
instances. To reuse an existing connection between a particular JVM and the
cluster, set ENABLE_SERVER_AFFINITY to true in the hashtable of
weblogic.jndi.WLContext properties you specify when obtaining context. (If a
connection is not available, a new connection is created.)
ENABLE_SERVER_AFFINITY is only supported when the context is requested from
the cluster address.

Server Affinity and IIOP Client Authentication Using CSIv2

If you use WebLogic Server's Common Secure Interoperability (CSIv2) functionality to
support stateful interactions with WebLogic Server's J2EE Application Client ("thin
client"), you must use an affinity-based load balancing algorithm to ensure that method
calls stick to a server instance. Otherwise, all remote calls will be authenticated. To
prevent redundant authentication of stateful CSIv2 clients, use one of the load balancing
algorithms described in Round-Robin Affinity, Weight-Based Affinity, and Random-
Affinity.
 Round-Robin Affinity, Weight-Based Affinity, and Random-
Affinity
WebLogic Server has three load balancing algorithms that provide server affinity:

 round-robin-affinity
 weight-based-affinity
 random-affinity

Server affinity is supported for all types of RMI objects including JMS objects, all EJB
home interfaces, and stateless EJB remote interfaces.

The server affinity algorithms consider existing connections between an external Java
client and server instances in balancing the client load among WebLogic server instances.
Server affinity:

 turns off load balancing between external Java clients and server instances
 causes method calls from an external Java client to stick to a server
instance to which the client has an open connection, assuming that the connection
supports the necessary protocol and QOS
 in the case of failure, causes the client to failover to a server instance to
which it has an open connection, assuming that the connection supports the
necessary protocol and QOS
 does not affect the load balancing performed for server-to-server
connections

Server Affinity Examples

The following examples illustrate the effect of server affinity under a variety of
circumstances. In each example, the objects deployed are configured for round-robin-
affinity.

Example 1—Context from cluster

In this example, the client obtains context from the cluster. Lookups on the context and
object calls stick to a single connection. Requests for new initial context are load
balanced on a round-robin basis.

Figure 5-1 Client Obtains Context From the Cluster

1. Client requests a new initial context from the cluster
(Provider_URL=clusteraddress) and obtains the context from MS1.

2. Client does a lookup on the context for Object A. The lookup goes to MS1.
3. Client issues a call to Object A. The call goes to MS1, to which the client is
already connected. Additional method calls to Object A stick to MS1.

4. Client requests a new initial context from the cluster

(Provider_URL=clusteraddress) and obtains the context from MS2.

5. Client does a lookup on the context for Object B. The call goes to MS2, to
which the client is already connected. Additional method calls to Object B stick to
MS2.

Example 2—Server Affinity and Failover

This example illustrates the effect that server affinity has on object failover. When a
Managed Server goes down, the client fails over to another Managed Server to which it
has a connection.

Figure 5-2 Server Affinity and Failover

1. Client requests new initial context from MS1.
2. Client does a lookup on the context for Object A. The lookup goes to MS1.
3. Client makes a call to Object A. The call goes to MS1, to which the client is
already connected. Additional calls to Object A stick to MS1.
4. The client obtains a stub for Object C, which is pinned to MS3. The client
opens a connection to MS3.
5. MS1 fails.
6. Client makes a call to Object A.The client no longer has a connection to
MS1. Because the client is connected to MS3, it fails over to a replica of Object A
on MS3.

Example 3—Server affinity and server-to-server connections

This example illustrates the fact that server affinity does not affect the connections
between server instances.

Figure 5-3 Server Affinity and Server-to-Server Connections

 A JSP on MS4 obtains a stub for Object B.
2. The JSP selects a replica on MS1. For each method call, the JSP cycles
through the Managed Servers upon which Object B is available, on a round-robin
basis.

Parameter-Based Routing for Clustered Objects

Parameter-based routing allows you to control load balancing behavior at a lower level.
Any clustered object can be assigned a CallRouter. This is a class that is called before
each invocation with the parameters of the call. The CallRouter is free to examine the
parameters and return the name server to which the call should be routed. For information
about creating custom CallRouter classes, see Parameter-Based Routing for Clustered
Objects in Programming WebLogic RMI.

Optimization for Collocated Objects

WebLogic Server does not always load balance an object's method calls. In most cases, it
is more efficient to use a replica that is collocated with the stub itself, rather than using a
replica that resides on a remote server. The following figure illustrates this.

Figure 5-4 Collocation Optimization Overrides Load Balancer Logic for

Method Call
In this example, a client connects to a servlet hosted by the first WebLogic Server
instance in the cluster. In response to client activity, the servlet obtains a replica-aware
stub for Object A. Because a replica of Object A is also available on the same server
instance, the object is said to be collocated with the client's stub.

WebLogic Server always uses the local, collocated copy of Object A, rather than
distributing the client's calls to other replicas of Object A in the cluster. It is more
efficient to use the local copy, because doing so avoids the network overhead of
establishing peer connections to other servers in the cluster.

This optimization is often overlooked when planning WebLogic Server clusters. The
collocation optimization is also frequently confusing for administrators or developers
who expect or require load balancing on each method call. If your Web application is
deployed to a single cluster, the collocation optimization overrides any load balancing
logic inherent in the replica-aware stub.

If you require load balancing on each method call to a clustered object, see
Recommended Multi-Tier Architecture for information about how to plan your
WebLogic Server cluster accordingly.

Transactional Collocation
As an extension to the basic collocation strategy, WebLogic Server attempts to use
collocated clustered objects that are enlisted as part of the same transaction. When a
client creates a UserTransaction object, WebLogic Server attempts to use object
replicas that are collocated with the transaction. This optimization is depicted in the
figure below.

Figure 5-5 Collocation Optimization Extends to Other Objects in

Transaction
In this example, a client attaches to he first WebLogic Server instance in the cluster and
obtains a UserTransaction object. After beginning a new transaction, the client looks up
Objects A and B to do the work of the transaction. In this situation WebLogic Server
always attempts to use replicas of A and B that reside on the same server as the
UserTransaction object, regardless of the load balancing strategies in the stubs for A
and B.

This transactional collocation strategy is even more important than the basic optimization
described in Optimization for Collocated Objects. If remote replicas of A and B were
used, added network overhead would be incurred for the duration of the transaction,
because the peer connections for A and B would be locked until the transaction
committed. Furthermore, WebLogic Server would need to employ a multi-tiered JDBC
connection to commit the transaction, incurring additional network overhead.

By using collocating clustered objects during a transaction, WebLogic Server reduces the
network load for accessing the individual objects. The server also can make use of a
single-tiered JDBC connection, rather than a multi-tiered connection, to do the work of
the transaction.

Load Balancing for JMS

WebLogic Server JMS supports server affinity for distributed JMS destinations and client
connections.

By default, a WebLogic Server cluster uses the round-robin method to load balance
objects. To use a load balancing algorithm that provides server affinity for JMS objects,
you must configure the desired method for the cluster as a whole. You can configure the
load balancing algorithm by using the Administration Console to set
weblogic.cluster.defaultLoadAlgorithm. For instructions, see Configure Load
Balancing Method for EJBs and RMIs.

Server Affinity for Distributed JMS Destinations

Server affinity is supported for JMS applications that use the distributed destination
feature; this feature is not supported for standalone destinations. If you configure server
affinity for JMS connection factories, a server instance that is load balancing consumers
or producers across multiple members of a distributed destination will first attempt to
load balance across any destination members that are also running on the same server
instance.

For detailed information on how the JMS connection factory's Server Affinity Enabled
option affects the load balancing preferences for distributed destination members, see
How Distributed Destination Load Balancing Is Affected When Using the Server Affinity
Enabled Attribute in Programming WebLogic JMS.

Initial Context Affinity and Server Affinity for Client Connections

A system administrator can establish load balancing of JMS destinations across multiple
servers in a cluster by configuring multiple JMS servers and using targets to assign them
to the defined WebLogic Servers. Each JMS server is deployed on exactly one WebLogic
Server and handles requests for a set of destinations. During the configuration phase, the
system administrator enables load balancing by specifying targets for JMS servers. For
instructions on setting up targets, see Configure Migratable Targets for Pinned Services.
For instructions on deploying a JMS server to a migratable target, see Deploying,
Activating, and Migrating Migratable Services.

A system administrator can establish cluster-wide, transparent access to destinations from

any server in the cluster by configuring multiple connection factories and using targets to
assign them to WebLogic Servers. Each connection factory can be deployed on multiple
WebLogic Servers. Connection factories are described in more detail in Connection
Factory in Programming WebLogic JMS.

The application uses the Java Naming and Directory Interface (JNDI) to look up a
connection factory and create a connection to establish communication with a JMS
server. Each JMS server handles requests for a set of destinations. Requests for
destinations not handled by a JMS server are forwarded to the appropriate server.

WebLogic Server provides server affinity for client connections. If an application has a
connection to a given server instance, JMS will attempt to establish new JMS connections
to the same server instance.

When creating a connection, JMS will try first to achieve initial context affinity. It will
attempt to connect to the same server or servers to which a client connected for its initial
context, assuming that the server instance is configured for that connection factory. For
example, if the connection factory is configured for servers A and B, but the client has an
InitialContext on server C, then the connection factory will not establish the new
connection with A, but will choose between servers B and C.

If a connection factory cannot achieve initial context affinity, it will try to provide
affinity to a server to which the client is already connected. For instance, assume the
client has an InitialContext on server A and some other type of connection to server B. If
the client then uses a connection factory configured for servers B and C it will not
achieve initial context affinity. The connection factory will instead attempt to achieve
server affinity by trying to create a connection to server B, to which it already has a
connection, rather than server C.

If a connection factory cannot provide either initial context affinity or server affinity, then
the connection factory is free to make a connection wherever possible. For instance,
assume a client has an initial context on server A, no other connections and a connection
factory configured for servers B and C. The connection factory is unable to provide any
affinity and is free to attempt new connections to either server B or C.

Note: In the last case, if the client attempts to make a second connection using the same
connection factory, it will go to the same server as it did on the first attempt. That is, if it
chose server B for the first connection, when the second connection is made, the client
will have a connection to server B and the server affinity rule will be enforced.

Load Balancing for JDBC Connections

Load balancing of JDBC connection requires the use of a multi data source configured
for load balancing. Load balancing support is an option you can choose when configuring
a multi data source.

A load balancing multi data source provides the high available behavior described in
Failover and JDBC Connections, and in addition, balances the load among the data
sources in the multi data source. A multi data source has an ordered list of data sources it
contains. If you do not configure the multi data source for load balancing, it always
attempts to obtain a connection from the first data source in the list. In a load-balancing
multi data source, the data sources it contains are accessed using a round-robin scheme.
In each successive client request for a multi data source connection, the list is rotated so
the first pool tapped cycles around the list.

For instructions on clustering JDBC objects, see Configure Clustered JDBC.

How WebLogic Server Detects Failures

WebLogic Server instances in a cluster detect failures of their peer server instances by
monitoring:

 Socket connections to a peer server

 Regular server heartbeat messages

Failure Detection Using IP Sockets

WebLogic Server instances monitor the use of IP sockets between peer server instances
as an immediate method of detecting failures. If a server connects to one of its peers in a
cluster and begins transmitting data over a socket, an unexpected closure of that socket
causes the peer server to be marked as "failed," and its associated services are removed
from the JNDI naming tree.

The WebLogic Server "Heartbeat"

If clustered server instances do not have opened sockets for peer-to-peer communication,
failed servers may also be detected via the WebLogic Server heartbeat. All server
instances in a cluster use multicast to broadcast regular server heartbeat messages to other
members of the cluster. Each heartbeat message contains data that uniquely identifies the
server that sends the message. Servers broadcast their heartbeat messages at regular
intervals of 10 seconds. In turn, each server in a cluster monitors the multicast address to
ensure that all peer servers' heartbeat messages are being sent.

If a server monitoring the multicast address misses three heartbeats from a peer server
(i.e., if it does not receive a heartbeat from the server for 30 seconds or longer), the
monitoring server marks the peer server as "failed." It then updates its local JNDI tree, if
necessary, to retract the services that were hosted on the failed server.

In this way, servers can detect failures even if they have no sockets open for peer-to-peer
communication.

Note: For more information about how WebLogic Server uses IP sockets and multicast
communications see WebLogic Server Communication in a Cluster.

Cluster Architectures

This following sections describe alternative architectures for a WebLogic Server cluster:

 Architectural and Cluster Terminology

 Recommended Basic Architecture
 Recommended Multi-Tier Architecture
 Recommended Proxy Architectures
 Security Options for Cluster Architectures

Architectural and Cluster Terminology

This section defines terms used in this document.

Architecture

In this context the architecture refers to how the tiers of an application are deployed to
one or more clusters.

Web Application Tiers

A Web application is divided into several "tiers" that correspond to the logical services
the application provides. Because not all Web applications are alike, your application
may not utilize all of the tiers described below. Also keep in mind that the tiers represent
logical divisions of an application's services, and not necessarily physical divisions
between hardware or software components. In some cases, a single machine running a
single WebLogic Server instance can provide all of the tiers described below.
 Web Tier

The web tier provides static content (for example, simple HTML pages) to
clients of a Web application. The web tier is generally the first point of
contact between external clients and the Web application. A simple Web
application may have a web tier that consists of one or more machines
running WebLogic Express, Apache, Netscape Enterprise Server, or
Microsoft Internet Information Server.

 Presentation Tier

The presentation tier provides dynamic content (for example, servlets or Java
Server Pages) to clients of a Web application. A cluster of WebLogic Server
instances that hosts servlets and/or JSPs comprises the presentation tier of a
web application. If the cluster also serves static HTML pages for your
application, it encompasses both the web tier and the presentation tier.

 Object Tier

The object tier provides Java objects (for example, Enterprise JavaBeans or
RMI classes) and their associated business logic to a Web application. A
WebLogic Server cluster that hosts EJBs provides an object tier.

Combined Tier Architecture

A cluster architecture in which all tiers of the Web application are deployed to a single
WebLogic Server cluster is called a combined tier architecture.

De-Militarized Zone (DMZ)

The De-Militarized Zone (DMZ) is a logical collection of hardware and services that is
made available to outside, untrusted sources. In most Web applications, a bank of Web
servers resides in the DMZ to allow browser-based clients access to static HTML content.

The DMZ may provide security against outside attacks to hardware and software.
However, because the DMZ is available to untrusted sources, it is less secure than an
internal system. For example, internal systems may be protected by a firewall that denies
all outside access. The DMZ may be protected by a firewall that hides access to
individual machines, applications, or port numbers, but it still permits access to those
services from untrusted clients.

Load Balancer

In this document, the term load balancer describes any technology that distributes client
connection requests to one or more distinct IP addresses. For example, a simple Web
application may use the DNS round-robin algorithm as a load balancer. Larger
applications generally use hardware-based load balancing solutions such as those from
Alteon WebSystems, which may also provide firewall-like security capabilities.
Load balancers provide the capability to associate a client connection with a particular
server in the cluster, which is required when using in-memory replication for client
session information. With certain load balancing products, you must configure the cookie
persistence mechanism to avoid overwriting the WebLogic Server cookie which tracks
primary and secondary servers used for in-memory replication. See For a discussion of
external load balancers, session cookie persistence, and the WebLogic Server session
cookie, see Load Balancing HTTP Sessions with an External Load Balancer on page 5-2
for more information.

Proxy Plug-In

A proxy plug-in is a WebLogic Server extension to an HTTP server—such as Apache,

Netscape Enterprise Server, or Microsoft Internet Information Server—that accesses
clustered servlets provided by a WebLogic Server cluster. The proxy plug-in contains the
load balancing logic for accessing servlets and JSPs in a WebLogic Server cluster. Proxy
plug-ins also contain the logic for accessing the replica of a client's session state if the
primary WebLogic Server hosting the session state fails.

Recommended Basic Architecture

The recommended basic architecture is a combined tier architecture—all tiers of the Web
application are deployed to the same WebLogic Server cluster. This architecture is
illustrated in the following figure.

Figure 7-1 Recommended Basic Architecture

The benefits of the Recommended Basic Architecture are:

 Ease of administration
 Because a single cluster hosts static HTTP pages, servlets, and EJBs, you can
configure the entire Web application and deploy/undeploy objects using the
WebLogic Server Console. You do not need to maintain a separate bank of
Web servers (and configure WebLogic Server proxy plug-ins) to benefit from
clustered servlets.

 Flexible load balancing

Using load balancing hardware directly in front of the WebLogic Server

cluster enables you to use advanced load balancing policies for accessing
both HTML and servlet content. For example, you can configure your load
balancer to detect current server loads and direct client requests
appropriately.

 Robust security

Placing a firewall in front of your load balancing hardware enables you to set
up a De-Militarized Zone (DMZ) for your web application using minimal
firewall policies.

 Optimal performance

The combined tier architecture offers the best performance for applications in
which most or all of the servlets or JSPs in the presentation tier typically
access objects in the object tier, such as EJBs or JDBC objects

Note: When using a third-party load balancer with in-memory session replication, you
must ensure that the load balancer maintains a client's connection to the WebLogic Server
instance that hosts its primary session state (the point-of-contact server). For more
information about load balancers, see For a discussion of external load balancers, session
cookie persistence, and the WebLogic Server session cookie, see Load Balancing HTTP
Sessions with an External Load Balancer on page 5-2.

When Not to Use a Combined Tier Architecture

While a combined tier architecture, such as the Recommended Basic Architecture, meets
the needs of many Web applications, it limits your ability to fully employ the load
balancing and failover capabilities of a cluster. Load balancing and failover can be
introduced only at the interfaces between Web application tiers, so, when tiers are
deployed to a single cluster, you can only load balance between clients and the cluster.

Because most load balancing and failover occurs between clients and the cluster itself, a
combined tier architecture meets the needs of most Web applications.

However, combined-tier clusters provide no opportunity for load balancing method calls
to clustered EJBs. Because clustered objects are deployed on all WebLogic Server
instances in the cluster, each object instance is available locally to each server. WebLogic
Server optimizes method calls to clustered EJBs by always selecting the local object
instance, rather than distributing requests to remote objects and incurring additional
network overhead.
This collocation strategy is, in most cases, more efficient than load balancing each
method request to a different server. However, if the processing load to individual servers
becomes unbalanced, it may eventually become more efficient to submit method calls to
remote objects rather than process methods locally.

To utilize load balancing for method calls to clustered EJBs, you must split the
presentation and object tiers of the Web application onto separate physical clusters, as
described in the following section.

Consider the frequency of invocations of the object tier by the presentation tier when
deciding between a combined tier and multi-tier architecture. If presentation objects
usually invoke the object tier, a combined tier architecture may offer better performance
than a multi-tier architecture.

Recommended Multi-Tier Architecture

This section describes the Recommended Multi-Tier Architecture, in which different tiers
of your application are deployed to different clusters.

The recommended multi-tier architecture uses two separate WebLogic Server clusters:
one to serve static HTTP content and clustered servlets, and one to serve clustered EJBs.
The multi-tier cluster is recommended for Web applications that:

 Require load balancing for method calls to clustered EJBs.

 Require more flexibility for balancing the load between servers that provide
HTTP content and servers that provide clustered objects.
 Require higher availability (fewer single points of failure).

Note: Consider the frequency of invocations from the presentation tier to the object tier
when considering a multi-tier architecture. If presentation objects usually invoke the
object tier, a combined tier architecture may offer better performance than a multi-tier
architecture.

The following figure depicts the recommended multi-tier architecture.

Figure 7-2 Recommended Multi-Tier Architecture

 Physical Hardware and Software Layers

In the Recommended Multi-Tier Architecture the application tiers are hosted on two
separate physical layers of hardware and software.

Web/Presentation Layer

The web/presentation layer consists of a cluster of WebLogic Server instances dedicated

to hosting static HTTP pages, servlets, and JSPs. This servlet cluster does not host
clustered objects. Instead, servlets in the presentation tier cluster act as clients for
clustered objects, which reside on an separate WebLogic Server cluster in the object
layer.

Object Layer

The object layer consists of a cluster of WebLogic Server instances that hosts only
clustered objects—EJBs and RMI objects as necessary for the web application. By
hosting the object tier on a dedicated cluster, you lose the default collocation optimization
for accessing clustered objects described in Optimization for Collocated Objects.
However, you gain the ability to load balance on each method call to certain clustered
objects, as described in the following section.

Benefits of Multi-Tier Architecture

The multi-tier architecture provides these advantages:

 Load Balancing EJB Methods

 By hosting servlets and EJBs on separate clusters, servlet method calls to
EJBs can be load balanced across multiple servers. This process is described
in detail in Load Balancing Clustered Objects in a in Multi-Tier Architecture.

 Improved Server Load Balancing

Separating the presentation and object tiers onto separate clusters provides
more options for distributing the load of the web application. For example, if
the application accesses HTTP and servlet content more often than EJB
content, you can use a large number of WebLogic Server instances in the
presentation tier cluster to concentrate access to a smaller number of servers
hosting EJBs.

 Higher Availability

By utilizing additional WebLogic Server instances, the multi-tier architecture

has fewer points of failure than the basic cluster architecture. For example, if
a WebLogic Server that hosts EJBs fails, the HTTP- and servlet-hosting
capacity of the Web application is not affected.

 Improved Security Options

By separating the presentation and object tiers onto separate clusters, you can
use a firewall policy that places only the servlet/JSP cluster in the DMZ.
Servers hosting clustered objects can be further protected by denying direct
access from untrusted clients. For more information, see Security Options for
Cluster Architectures.

Load Balancing Clustered Objects in a in Multi-Tier Architecture

WebLogic Server's collocation optimization for clustered objects, described in

Optimization for Collocated Objects, relies on having a clustered object (the EJB or RMI
class) hosted on the same server instance as the replica-aware stub that calls the object.

The net effect of isolating the object tier is that no client (HTTP client, Java client, or
servlet) ever acquires a replica-aware stub on the same server that hosts the clustered
object. Because of this, WebLogic Server cannot use its collocation optimization
(described in Optimization for Collocated Objects), and servlet calls to clustered objects
are automatically load balanced according to the logic contained in the replica-aware
stub. The following figure depicts a client accessing a clustered EJB instance in the
multi-tier architecture.

Figure 7-3 Load Balancing Objects in a Multi-Tier Architecture

Tracing the path of the client connection, you can see the implication of isolating the
object tier onto separate hardware and software:

1. An HTTP client connects to one of several WebLogic Server instances in the

web/servlet cluster, going through a load balancer to reach the initial server.
2. The client accesses a servlet hosted on the WebLogic Server cluster.
3. The servlet acts as a client to clustered objects required by the web
application. In the example above, the servlet accesses a stateless session EJB.

The servlet looks up the EJB on the WebLogic Server cluster that hosts
clustered objects. The servlet obtains a replica-aware stub for the bean, which
lists the addresses of all servers that host the bean, as well as the load
balancing logic for accessing bean replicas.

Note: EJB replica-aware stubs and EJB home load algorithms are specified
using elements of the EJB deployment descriptor. See weblogic-ejb-jar.xml
Deployment Descriptor Reference in Programming WebLogic Enterprise
JavaBeans for more information.

4. When the servlet next accesses the EJB (for example, in response to
another client), it uses the load-balancing logic present in the bean's stub to locate
a replica. In the example above, multiple method calls are directed using the
round-robin algorithm for load balancing.

In this example, if the same WebLogic Server cluster hosted both servlets and EJBs (as in
the Recommended Basic Architecture), WebLogic Server would not load balance
requests for the EJB. Instead, the servlet would always invoke methods on the EJB
replica hosted on the local server. Using the local EJB instance is more efficient than
making remote method calls to an EJB on another server. However, the multi-tier
architecture enables remote EJB access for applications that require load balancing for
EJB method calls.
 Configuration Considerations for Multi-Tier Architecture

IP Socket Usage

Because the multi-tier architecture provides load balancing for clustered object calls, the
system generally utilizes more IP sockets than a combined-tier architecture. In particular,
during peak socket usage, each WebLogic Server in the cluster that hosts servlets and
JSPs may potentially use a maximum of:

 One socket for replicating HTTP session states between primary and
secondary servers, plus
 One socket for each WebLogic Server in the EJB cluster, for accessing
remote objects

For example, in Figure 7-2, each server in the servlet/JSP cluster could potentially open a
maximum of five sockets. This maximum represents a worst-case scenario where primary
and secondary session states are equally dispersed throughout the servlet cluster, and
each server in the servlet cluster simultaneously accesses a remote object on each server
in the object cluster. In most cases, the number of sockets actual sockets in use would be
less than this maximum.

If you use a pure-Java sockets implementation with the multi-tier architecture, ensure that
you configure enough socket reader threads to accommodate the maximum potential
socket usage. For details, see Configuring Reader Threads for Java Socket
Implementation.

Hardware Load Balancers

Because the multi-tier architecture uses a hardware load balancer, you must configure the
load balancer to maintain a "sticky" connection to the client's point-of-contact server if
you use in-memory session state replication. For details, see Configure Load Balancing
Method for EJBs and RMIs.

Limitations of Multi-Tier Architectures

This section summarizes the limitations of multi-tier cluster architectures.

No Collocation Optimization

Because the Recommended Multi-Tier Architecture cannot optimize object calls using
the collocation strategy, the Web application incurs network overhead for all method
calls to clustered objects. This overhead may be acceptable, however, if your Web
application requires any of the benefits described in Benefits of Multi-Tier Architecture.

For example, if your Web clients make heavy use of servlets and JSPs but access a
relatively small set of clustered objects, the multi-tier architecture enables you to
concentrate the load of servlets and object appropriately. You may configure a servlet
cluster of ten WebLogic Server instances and an object cluster of three WebLogic Server
instances, while still fully utilizing each server's processing power.
 Firewall Restrictions

If you place a firewall between the servlet cluster and object cluster in a multi-tier
architecture, you must bind all servers in the object cluster to public DNS names, rather
than IP addresses. Binding those servers with IP addresses can cause address translation
problems and prevent the servlet cluster from accessing individual server instances.

If the internal and external DNS names of a WebLogic Server instance are not identical,
use the ExternalDNSName attribute for the server instance to define the server's external
DNS name. Outside the firewall the ExternalDNSName should translate to external IP
address of the server.

Use of ExternalDNSName is required for configurations in which a firewall is performing

Network Address Translation, unless clients are accessing WebLogic Server using t3 and
the default channel. For instance, ExternalDNSName is required for configurations in
which a firewall is performing Network Address Translation, and clients are accessing
WebLogic Server using HTTP via a proxy plug-in.

Recommended Proxy Architectures

You can configure WebLogic Server clusters to operate alongside existing Web servers.
In such an architecture, a bank of Web servers provides static HTTP content for the Web
application, using a WebLogic proxy plug-in or HttpClusterServlet to direct servlet
and JSP requests to a cluster.

The following sections describe two alternative proxy architectures.

Two-Tier Proxy Architecture

The two-tier proxy architecture illustrated in the following figure is similar to the
Recommended Basic Architecture, except that static HTTP servers are hosted on a bank
of Web servers.

Figure 7-4 Two-Tier Proxy Architecture

 Physical Hardware and Software Layers

The two-tier proxy architecture contains two physical layers of hardware and software.

Web Layer

The proxy architecture utilizes a layer of hardware and software dedicated to the task of
providing the application's web tier. This physical web layer can consist of one or more
identically-configured machines that host one of the following application combinations:

 WebLogic Server with the HttpClusterServlet

 Apache with the WebLogic Server Apache proxy plug-in

 Netscape Enterprise Server with the WebLogic Server NSAPI proxy plug-in
 Microsoft Internet Information Server with the WebLogic Server Microsoft-
IIS proxy plug-in

Regardless of which Web server software you select, keep in mind that the physical tier
of Web servers should provide only static Web pages. Dynamic content—servlets and
JSPs—are proxied via the proxy plug-in or HttpClusterServlet to a WebLogic Server
cluster that hosts servlets and JSPs for the presentation tier.

Servlet/Object Layer

The recommended two-tier proxy architecture hosts the presentation and object tiers on a
cluster of WebLogic Server instances. This cluster can be deployed either on a single
machine or on multiple separate machines.
The Servlet/Object layer differs from the combined-tier cluster described in
Recommended Basic Architecture in that it does not provide static HTTP content to
application clients.

Multi-Tier Proxy Architecture

You can also use a bank of Web servers as the front-end to a pair of WebLogic Server
clusters that host the presentation and object tiers. This architecture is shown in the
following figure.

Figure 7-5 Multi-Tier Proxy Architecture

This architecture provides the same benefits (and the same limitations) as the
Recommended Multi-Tier Architecture. It differs only insofar as the web tier is placed on
a separate bank of Web servers that utilize WebLogic proxy plug-ins.

Proxy Architecture Benefits

Using standalone Web servers and proxy plug-ins provides the following advantages:

 Utilize Existing Hardware

 If you already have a Web application architecture that provides static HTTP
content to clients, you can easily integrate existing Web servers with one or
more WebLogic Server clusters to provide dynamic HTTP and clustered
objects.

 Familiar Firewall Policies

Using a Web server proxy at the front-end of your Web application enables
you to use familiar firewall policies to define your DMZ. In general, you can
continue placing the Web servers in your DMZ while disallowing direct
connections to the remaining WebLogic Server clusters in the architecture.
The figures above depict this DMZ policy.

Proxy Architecture Limitations

Using standalone Web servers and proxy plug-ins limits your Web application in the
following ways:

 Additional administration

The Web servers in the proxy architecture must be configured using third-
party utilities, and do not appear within the WebLogic Server administrative
domain. You must also install and configure WebLogic proxy plug-ins to the
Web servers in order to benefit from clustered servlet access and failover.

 Limited Load Balancing Options

When you use proxy plug-ins or the HttpClusterServlet to access

clustered servlets, the load balancing algorithm is limited to a simple round-
robin strategy.

Proxy Plug-In Versus Load Balancer

Using a load balancer directly with a WebLogic Server cluster provides several benefits
over proxying servlet requests. First, using WebLogic Server with a load balancer
requires no additional administration for client setup—you do not need to set up and
maintain a separate layer of HTTP servers, and you do not need to install and configure
one or more proxy plug-ins. Removing the Web proxy layer also reduces the number of
network connections required to access the cluster.

Using load balancing hardware provides more flexibility for defining load balancing
algorithms that suit the capabilities of your system. You can use any load balancing
strategy (for example, load-based policies) that your load balancing hardware supports.
With proxy plug-ins or the HttpClusterServlet, you are limited to a simple round-
robin algorithm for clustered servlet requests.

Note, however, that using a third-party load balancer may require additional
configuration if you use in-memory session state replication. In this case, you must
ensure that the load balancer maintains a "sticky" connection between the client and its
point-of-contact server, so that the client accesses the primary session state information.
When using proxy plug-ins, no special configuration is necessary because the proxy
automatically maintains a sticky connection.

Security Options for Cluster Architectures

The boundaries between physical hardware/software layers in the recommended

configurations provide potential points for defining your Web application's De-
Militarized Zone (DMZ). However, not all boundaries can support a physical firewall,
and certain boundaries can support only a subset of typical firewall policies.

The sections that follow describe several common ways of defining your DMZ to create
varying levels of application security.

Basic Firewall for Proxy Architectures

The basic firewall configuration uses a single firewall between untrusted clients and the
Web server layer, and it can be used with either the Recommended Basic Architecture or
Recommended Multi-Tier Architecture cluster architectures.

Figure 7-6 Basic Proxy with Firewall Architecture

In the above configuration, the single firewall can use any combination of policies
(application-level restrictions, NAT, IP masquerading) to filter access to three HTTP
servers. The most important role for the firewall is to deny direct access to any other
servers in the system. In other words, the servlet layer, the object layer, and the database
itself must not be accessible from untrusted clients.
Note that you can place the physical firewall either in front of or behind the Web servers
in the DMZ. Placing the firewall in front of the Web servers simplifies your firewall
policies, because you need only permit access to the web servers and deny access to all
other systems.

Firewall Between Proxy Layer and Cluster

If you place a firewall between the proxy layer and the cluster, follow these configuration
guidelines:

 Bind to clustered server instances using publicly-listed DNS names, rather

than IP addresses, to ensure that the proxy plug-ins can connect to each server in
the cluster without address translation error that might otherwise occur, as
described in Firewall Considerations.
 If the internal and external DNS names of a clustered server instance are
not identical, use the ExternalDNSName attribute for the server instance to define
the its external DNS name. Outside the firewall the ExternalDNSName should
translate to external IP address of the server instance.

Note: If the clustered servers segregate https and http traffic on a pair of custom
channels, see Channels, Clusters, and Firewalls in Designing and Configuring WebLogic
Server Environments.

DMZ with Basic Firewall Configurations

By denying access to all but the Web server layer, the basic firewall configuration creates
a small-footprint DMZ that includes only three Web servers. However, a more
conservative DMZ definition might take into account the possibility that a malicious
client may gain access to servers hosting the presentation and object tiers.

For example, assume that a hacker gains access to one of the machines hosting a Web
server. Depending on the level of access, the hacker may then be able to gain information
about the proxied servers that the Web server accesses for dynamic content.

If you choose to define your DMZ more conservatively, you can place additional
firewalls using the information in Additional Security for Shared Databases.

Combining Firewall with Load Balancer

If you use load balancing hardware with a recommended cluster architecture, you must
decide how to deploy the hardware in relationship to the basic firewall. Although many
hardware solutions provide security features in addition to load balancing services, most
sites rely on a firewall as the first line of defense for their Web applications. In general,
firewalls provide the most well-tested and familiar security solution for restricting web
traffic, and should be used in front of load balancing hardware, as shown below.

Figure 7-7 Basic Proxy with Firewall and Load Balancer Architecture
The above setup places the load balancer within the DMZ along with the web tier. Using
a firewall in this configuration can simplify security policy administration, because the
firewall need only limit access to the load balancer. This setup can also simplify
administration for sites that support internal clients to the Web application, as described
below.

Expanding the Firewall for Internal Clients

If you support internal clients that require direct access to your Web application (for
example, remote machines that run proprietary Java applications), you can expand the
basic firewall configuration to allow restricted access to the presentation tier. The way in
which you expand access to the application depends on whether you treat the remote
clients as trusted or untrusted connections.

If you use a Virtual Private Network (VPN) to support remote clients, the clients may be
treated as trusted connections and can connect directly to the presentation tier going
through a firewall. This configuration is shown below.

Figure 7-8 VPN Users have Restricted Access Through Firewall

If you do not use a VPN, all connections to the Web application (even those from remote
sites using proprietary client applications) should be treated as untrusted connections. In
this case, you can modify the firewall policy to permit application-level connections to
WebLogic Server instances hosting the presentation tier, as shown in the following
figure.

Figure 7-9 Application Components Have Restricted Access Through

Firewall

Additional Security for Shared Databases

If you use a single database that supports both internal data and data for externally-
available Web applications, you should consider placing a hard boundary between the
object layer that accesses your database. Doing so simply reinforces the DMZ boundaries
described in Basic Firewall for Proxy Architectures by adding an additional firewall.

DMZ with Two Firewall Configuration

The following configuration places an additional firewall in front of a database server
that is shared by the Web application and internal (trusted) clients. This configuration
provides additional security in the unlikely event that the first firewall is breached, and a
hacker ultimately gains access to servers hosting the object tier. Note that this
circumstance should be extremely unlikely in a production environment—your site
should have the capability to detect and stop a malicious break-in long before a hacker
gains access to machines in the object layer.

Figure 7-10 DMZ with Two Firewalls Architecture

In the above configuration, the boundary between the object tier and the database is
hardened using an additional firewall. The firewall maintains a strict application-level
policy that denies access to all connections except JDBC connections from WebLogic
Servers hosting the object tier.

Troubleshooting Common Problems

This chapter provides guidelines on how to prevent cluster problems or troubleshoot them
if they do occur.

Before You Start the Cluster

You can do a number of things to help prevent problems before you boot the cluster.

Check for a Cluster License

Your WebLogic Server license must include the clustering feature. If you try to start a
cluster without a clustering license, you will see the error message Unable to find a
license for clustering.

Check the Server Version Numbers

All servers in the cluster must have the same major version number, but can have
different minor version numbers and service packs.

The cluster's Administration Server is typically not configured as a cluster member, but it
should run the same major version of WebLogic Server used on the managed servers.

Check the Multicast Address

A problem with the multicast address is one of the most common reasons a cluster does
not start or a server fails to join a cluster.

A multicast address is required for each cluster. The multicast address can be an IP
number between 224.0.0.0 and 239.255.255.255, or a host name with an IP address
within that range.

You can check a cluster's multicast address and port on its Configuration-->Multicast tab
in the Administration Console.

For each cluster on a network, the combination of multicast address and port must be
unique. If two clusters on a network use the same multicast address, they should use
different ports. If the clusters use different multicast addresses, they can use the same port
or accept the default port, 7001.

Before booting the cluster, make sure the cluster's multicast address and port are correct
and do not conflict with the multicast address and port of any other clusters on the
network.

The errors you are most likely to see if the multicast address is bad are:

Unable to create a multicast socket for clustering

Multicast socket send error

Multicast socket receive error

 Check the CLASSPATH Value

Make sure the value of CLASSPATH is the same on all managed servers in the cluster.
CLASSPATH is set by the setEnv script, which you run before you run
startManagedWebLogic to start the managed servers.

By default, setEnv sets this value for CLASSPATH (as represented on Windows systems):

set WL_HOME=C:\bea\weblogic700
set JAVA_HOME=C:\bea\jdk131
.
.
set CLASSPATH=%JAVA_HOME%\lib\tools.jar;
%WL_HOME%\server\lib\weblogic_sp.jar;
%WL_HOME%\server\lib\weblogic.jar;
%CLASSPATH%

If you change the value of CLASSPATH on one managed server, or change how setEnv
sets CLASSPATH, you must change it on all managed servers in the cluster.

Check the Thread Count

Each server instance in the cluster has a default execute queue, configured with a fixed
number of execute threads. To view the thread count for the default execute queue,
choose the Configure Execute Queue command on the Advanced Options portion of the
Configuration> General tab for the server. The default thread count for the default queue
is 15, and the minimum value is 5. If the value of Thread Count is below 5, change it to a
higher value so that the Managed Server does not hang on startup.

After You Start the Cluster

Check Your Commands

If the cluster fails to start, or a server fails to join the cluster, the first step is to check any
commands you have entered, such as startManagedWebLogic or a java interpreter
command, for errors and misspellings.

Generate a Log File

Before contacting BEA Technical Support for help with cluster-related problems, collect
diagnostic information. The most important information is a log file with multiple thread
dumps from a Managed Server. The log file is especially important for diagnosing cluster
freezes and deadlocks.

Remember: a log file that contains multiple thread dumps is a prerequisite for
diagnosing your problem.

1. Stop the server.

2. Remove or back up any log files you currently have. You should create a
new log file each time you boot a server, rather than appending to an existing log
file.
3. Start the server with this command, which turns on verbose garbage
collection and redirects both the standard error and standard output to a log file:
% java -ms64m -mx64m -verbose:gc -classpath $CLASSPATH
-Dweblogic.domain=mydomain -Dweblogic.Name=clusterServer1
-Djava.security.policy==$WL_HOME/lib/weblogic.policy
-Dweblogic.admin.host=192.168.0.101:7001
weblogic.Server >> logfile.txt

Redirecting both standard error and standard output places thread dump
information in the proper context with server informational and error
messages and provides a more useful log.

4. Continue running the cluster until you have reproduced the problem.

5. If a server hangs, use kill -3 or <Ctrl>-<Break> to create the necessary

thread dumps to diagnose your problem. Make sure to do this several times on
each server, spaced about 5-10 seconds apart, to help diagnose deadlocks.

Note: If you are running the JRockit JVM under Linux, see Getting a JRockit Thread
Dump Under Linux.

6. Compress the log file using a Unix utility:

% tar czf logfile.tar logfile.txt

- or zip it using a Windows utility.

7. Attach the compressed log file to an e-mail to your BEA Technical Support
representative. Do not cut and paste the log file into the body of an e-mail.
8. If the compressed log file is too large, you can use the BEA Customer
Support FTP site.

Getting a JRockit Thread Dump under Linux

If you use the JRockit JVM under Linux, use one of the following methods to generate a
thread dump.

 Use the weblogic.admin THREAD_DUMP command.

 If the JVM's management server is enabled (by starting the JVM with the
-Xmanagement option), you can generate a thread dump using the JRockit
Management Console.
 Use Kill -3 PID, where PID is the root of the process tree.

To obtain the root PID, perform a:

ps -efHl | grep 'java' **. **

using a grep argument that is a string that will be found in the process stack
that matches the server startup command. The first PID reported will be the
root process, assuming that the ps command has not been piped to another
routine.
 Under Linux, each execute thread appears as a separate process under the
Linux process stack. To use Kill -3 on Linux you supply must match PID of
the main WebLogic execute thread, otherwise no thread dump will be
produced.

Check Garbage Collection

If you are experiencing cluster problems, you should also check the garbage collection on
the managed servers. If garbage collection is taking too long, the servers will not be able
to make the frequent heartbeat signals that tell the other cluster members they are running
and available.

If garbage collection (either first or second generation) is taking 10 or more seconds, you
need to tune heap allocation (the msmx parameter) on your system.

Run utils.MulticastTest

You can verify that multicast is working by running utils.MulticastTest from one of
the managed servers. See Using the WebLogic Server Java Utilities in WebLogic Server
Command Reference.