WebLogic Server 8.1 Upgrade Guide
Upgrading WebLogic Server 6.x to version 8.1, under the simplest circumstances, involves changing your WebLogic Server start command scripts and environment settings.
BEA Systems recommends copying your WebLogic Server 6.x domain directory to a new directory. If you do this, ensure that relative paths to external files remain accurate.
Upgrading may also require changes specific to the subsytem being upgraded.
The following sections contain information necessary to upgrade your system from WebLogic Server 6.x to WebLogic Server 8.1:
For instructions on how to upgrade the Pet Store application from WebLogic Server 6.1 to WebLogic Server 8.1, see Upgrading the Pet Store Application from WebLogic Server 6.1 Service Pack 4 to WebLogic Server 8.1.
For information on upgrading to WebLogic Platform 8.1, see the Upgrading section of the WebLogic Server FAQs.
BEA WebLogic recommends that you locate domain directories outside the WebLogic Server installation directory.
.In WebLogic Server 6.x, domain directories were created within the directory structure of the WebLogic Server installation. In subsequent versions, domain directories can be in any location that can access the WebLogic Server installation and the JDK.
If you change the location of your domain directory, remember to update any custom tools or scripts relative to the new directory structure. Similarly, if you use a scripted tool for creating domains, change its scripts. The Configuration Wizard is the recommended tool for creating domains, and it can be scripted.
When you upgrade from WebLogic Server 6.x to 8.1, you are upgrading a WebLogic Server domain. For a full description of WebLogic Server domains see Overview of WebLogic Server Domains in Configuring and Managing WebLogic Server.
The configuration of a domain is stored in the config.xml
file of the domain directory on the Administration Server. config.xml
stores the name of the domain and the configuration parameter settings for each server instance, cluster, resource, and service in the domain.
The domain directory also contains server start scripts that start the Administration Server and the Managed Servers in the domain.
The domain directory structure should have a root directory with the same name as the domain, such as mydomain or petstore. This directory should contain the following:
config.xml
) for the domain. For more information about WebLogic Server domains, see WebLogic Server Domains in Configuring and Managing WebLogic Server.
To upgrade a domain with multiple server instances, upgrade as you would a single-server domain. In a nutshell, you upgrade a domain by installing WebLogic Server 8.1 alongside your 6.x installation, copying the contents of your 6.x domain into a new 8.1 domain directory, and changing the domain scripts and environment settings to point to the new 8.1 domain and server instances.
If the domain includes a cluster and you want to take advantage of new clustering features in WebLogic Server 8.1, refer to Setting Up WebLogic Clusters in Using WebLogic Server Clusters for WebLogic Server 8.1 cluster configuration guidelines.
As a prerequisite to performing the upgrade procedures in this section, install WebLogic Server 8.1 on all the machines that contain 6.x server instances whose domain you will upgrade. See Installing WebLogic Platform for installation instructions for WebLogic Server 8.1.
Shut down all server instances in the WebLogic Server 6.x domain you are upgrading.
Shutting down the servers ensures that any changes you have made to the domain or its applications have been persisted. See Starting and Stopping Servers: Quick Reference.
Create a new directory where your 8.1 domain will reside.
Consider that after you move the contents of your 7.0 domain directory to this new 8.1 domain directory, any references from within the 7.0 domain to resources outside the domain will need to change unless the new domain directory is in the same relative location to the external resources.
Copy the contents of your WebLogic Server 6.x domain directory to the new 8.1 domain directory, including the server start scripts and configuration settings (see Contents of a Domain Directory).
Note that once you have upgraded the domain to WebLogic Server 8.1, you may not be able to convert it back to WebLogic Server 6.x.
Note: At this point, application paths in this new domain which will become your 8.1 domain still point to the applications that were deployed in the 6.x domain. Do not try to start server instances in either domain until you have completed the domain conversion—if you simultaneously run server instances that deploy the same applications under different versions of WebLogic Server, problems are likely to occur.
In the new 8.1 domain directory, delete files with the .log
suffix, and the \.wlnotdelete
folder. These artifacts may contain 6.x-specific settings that can cause problems in the 8.1 domain.
Modify the server start scripts in the new 8.1 domain directory to point to WebLogic Server 8.1 server instances instead of 6.x server instances. Do this for all Administration Servers and Managed Servers in the upgraded domain.The names of default start scripts created with new WebLogic Server domains are startWebLogic.cmd
(or .sh
) (for Administration Servers) and startManagedWebLogic.cmd
(or .sh
) (for Managed Servers).
The server start scripts in both the 6.x and the 8.1 domains reference a server start script in the WL_HOME\server\bin
directory, where WL_HOME
is the WebLogic Server installation.
If your start script calls the startWLS.cmd
script in your WebLogic Server 6.x WL_HOME\server\bin
directory, change it to call instead the startWLS.cmd
in your WebLogic Server 8.1 WL_HOME\server\bin
directory.
Depending on your server start script, it is likely that you need to change the settings of several of its properties. See Modifying Start Scripts.
Upgrade your applications to WebLogic Server 8.1 by checking references to external resources, updating utilities and optionally your JVM, and upgrading EJBs and security and other factors.
In this step, you are making sure that when your application references an external file, it references the correct address of the external file. This may involve editing your application's deployment descriptor files and the domain configuration file, config.xml
.
WebLogic Server configurations rely on a number of files that can be stored anywhere on the file system (for example, log files, file-based repositories, the Java compiler). Unless all such external files are referenced using relative paths and are located in or below the domain directory, do one of the following:
Start WebLogic Server 8.1 Administration and Managed servers, and configure and deploy your applications.
Note: WebLogic Server 8.1 automatically updates configuration information in the 6.x config.xml
file to include WebLogic Server 8.1 information. In order for these changes to be retained between invocations of the server, the config.xml
file must be writable. If you have made your config.xml
read-only, access its file properties and change the attribute so that it is writable. For example, in Windows, right-click the file in Windows Explorer, select Properties, and make sure that the Read-Only attribute is unchecked.
For information about starting WebLogic Server 8.1, see Starting and Stopping Servers: Quick Reference.
For information about configuring and deploying your applications, see Deployment.
If you used WebLogic Server start scripts with a previous version of the product, modify them to work with WebLogic Server 8.1.
For a concrete example of a start script being modified, see Upgrading the Pet Store Application from WebLogic Server 6.1 Service Pack 4 to WebLogic Server 8.1.
In general, modify the start scripts as described here. Your domain's start scripts may differ significantly from the startWebLogic.cmd
(or .sh
) script on which the following instructions are based. These instructions are valid for both Administration Server start scripts and Managed Server start scripts—all server start scripts that reference the 7.0 servers must be made to reference the 8.1 servers.
These instructions assume that you have performed the first two steps in the previous section, Upgrading Your WebLogic Server 6.x Domain to Version 8.1 on page 3. That is, before performing the following steps you should have done the following:
@rem Check that script is being run from the appropriate directory
if not exist lib\weblogic.jar goto wrongplace
echo startWebLogic.cmd must be run from the config\mydomain directory. 1>&2
if exist "%JAVA_HOME%/bin/javac.exe" goto runWebLogic
echo Javac wasn't found in directory %JAVA_HOME%/bin.
echo Please edit the startWebLogic.cmd script so that the JAVA_HOME
echo variable points to the root directory of your JDK installation.
WebLogic Server 8.1 installs the JVM, JDK 1.4.1, with the server installation. The setenv.cmd
and .sh
scripts provided with the server all point to the JVM. The latest information regarding certified JVMs is available at the Certifications Page.
This section walks through an actual upgrade of Sun's Pet Store application from WebLogic Server 6.1 to 8.1. This walkthrough uses the version of Pet Store that is included with WebLogic Server 6.x Service Pack 4.
In the following procedures it is assumed that WebLogic Server 6.1 and WebLogic Server 8.1 are both installed.
Before the actual upgrade steps, some problems in the Pet Store application need to be fixed. Stricter JSP and XML parsing in WebLogic Server 8.1 requires that minor XML and JSP errors that were acceptable in WebLogic Server 6.x be fixed.
This section describes corrections that need to be made to Pet Store in order to deploy it on WebLogic Server 8.1.
Versions of Pet Store from WebLogic Server 6.1SP6 and later do not require these repairs.
The procedures are as follows:
Following this preliminary section on repairing Pet Store in preparation for upgrade, Upgrade the Pet Store Domain on page 14 provides instructions for upgrading the Pet Store domain.
If you are upgrading from a WebLogic Server Service Pack later than 6.1 Service Pack 4, you do not need to complete this step.
Post-6.0 versions of WebLogic Server require that resource references defined in WebLogic-specific deployment descriptors match resource references in Sun deployment descriptors.
The following steps fix resource references that are mismatched in the Pet Store deployment descriptor files customer_weblogic_ejb.xml
and customer_ejb.xml
.
WL_HOME\samples\petStore\src\components\customer\src
. For example: <ejb-name>TheCustomer</ejb-name>
<ejb-ref-name>ejb/account/Account</ejb-ref-name>
<jndi-name>estore/account</jndi-name>
<ejb-ref-name>ejb/order/Order</ejb-ref-name>
<jndi-name>estore/order</jndi-name>
WL_HOME\samples\petStore\src\petstore\src\docroot\WEB-INF
, where WL_HOME
is the WebLogic Server 6.1 installation directory. For example:weblogic.xml
defines a number of resource-description
and ejb-reference-description
elements for the Web application. Add the following ejb-reference-description
to the file:
<ejb-reference-description>
<ejb-ref-name>ejb/profilemgr/ProfileMgr</ejb-ref-name>
<jndi-name>estore/profilemgr</jndi-name>
</ejb-reference-description>
Because of stricter XML parsing, WebLogic Server 8.1 will not allow this encoding error to pass, even though it was acceptable to earlier versions of WebLogic Server.
Delete a wildcard setting from a Pet Store property file because it may cause a security error.
Minor errors that were parsable in earlier versions of WebLogic Server cause errors in WebLogic Server 8.1 because JDK 1.4 does not accept them. The errors corrected in this section are property settings for which the method and setter properties do not agree.
Correcting the errors requires making changes to these source files:
ListTag.java
CartListTag.java
MyListTag.java
ProductItemListTag.java
ProductListTag.java
SearchListTag.java
All of these files are located in the WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list directory (where WL_HOME
is the WebLogic Server installation directory)
Use these steps to make the replacement in ListTag.java
:
WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list
. For example: WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list>notepad ListTag.java.
public void setNumItems(String numItemsStr) {
public void setStartIndex(String startIndexStr) {
startIndex = Integer.parseInt(startIndexStr);
}
Make the replacements in the rest of the files as follows:
WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list
. For example: WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list>notepad CartListTag.java.
public void setNumItems(String numItemsStr) {
super.setNumItems(numItemsStr);
}
public void setStartIndex(String startIndexStr) {
super.setNumItems(startIndexStr);
}
public void setNumItems(int numItems) {
super.setNumItems(numItems);
}
public void setStartIndex(int startIndex) {
super.setNumItems(startIndex);
}
MyListTag.java
ProductItemListTag.java
ProductListTag.java
SearchListTag.java
After making the corrections to Pet Store, rebuild the application.
In this upgrade procedure your WebLogic Server 8.1 configuration continues to point to the Cloudscape database used in WebLogic Server 6.1.
C:\petstorefrom61to81
, in which to upgrade the WebLogic Server 6.1 Pet Store domain to a WebLogic Server 8.1 Pet Store domain. In WebLogic Server 8.1, it is advisable to locate domains outside the WebLogic Server installation directory.
WL_HOME
directory to C:\petstorefrom61to81
: petstore.ear
and petstoreadmin.ear
to point to C:\petstorefrom61to81
. Replace: RootDirectory
setting, replace the WebLogic Server 6.x WL_HOME
path with the c:\petstorefrom61to81
path. That is, replace: where WL_HOME is the WebLogic Server 6.1 installation directory, becomes:
where WL_HOME
is the WebLogic Server 8.1 installation directory.
if not exist lib\weblogic.jar goto wrongplace
if not exist WL_HOME\server\lib\weblogic.jar goto wrongplace
where WL_HOME
is the WebLogic Server 8.1 installation directory.
set CLASSPATH=.;C:\bea\81feb26\weblogic81\server\lib\weblogic.jar;.WL_HOME61\samples\eval\cloudscape\lib\cloudscape.jar;.\config\petStore\serverclasses
set CLASSPATH=.;WL_HOME81\server\lib\weblogic.jar;.C:\petstorefrom61to81\samples\eval\cloudscape\lib\cloudscape.jar;C:\petstorefrom61to81\config\petstore\serverclasses
-Dbea.home
setting from the 6.x BEA_HOME
to the 8.1 BEA_HOME
, where BEA_HOME is the directory that contains the WebLogic Server installation directory. For example, change
WebLogic Server 8.1 has a new security architecture. For details on the changes, see What Changed in WebLogic Security in Introduction to WebLogic Security.
WebLogic Server 8.1 detects whether you are upgrading from an earlier WebLogic Server version such as 6.x or whether you are a new customer starting with version 8.1. If you are upgrading from WebLogic Server 6.x, you can run WebLogic Server 8.1 in Compatibility security, which allows you to keep your 6.x configuration of users and groups.
However, because some key 6.x security functionality is being deprecated—and because WebLogic Server 8.1 offers improved and expanded security features—customers are encouraged to upgrade their security configuration. This section contains the following upgrade issues and procedures:
The scope of security realms changed in WebLogic Server 8.1. In WebLogic Server 6.x, security realms provided authentication and authorization services. You chose from the File realm or a set of alternative security realms including the Lightweight Data Access Protocol (LDAP), Windows NT, UNIX or RDBMS realms. In addition, you could write a Custom security realm. For more information about WebLogic Server 6.x security realms, see Security Realms in Programming WebLogic Security.
In WebLogic Server 8.1, each security realm consists of a set of configured security providers, users, groups, security roles, and security policies. Authentication and Authorization providers within a security realm offer authentication and authorization services. For more information about WebLogic Server 8.1 security realms, see Security Realms in Introduction to WebLogic Security.
You have the following choices when upgrading a WebLogic Server 6.x security realm to WebLogic Server 8.1:
CompatibilityRealm
. For detailed information about booting WebLogic Server 8.1 in Compatibility security and using Compatibility security, see Using Compatibility Security in Managing WebLogic Security. Compatibility security also allows you to start exploring WebLogic Server 8.1 security features so you can later convert your 6.x security configuration to the new security mechanisms (such as security roles and security policies) that are available in WebLogic Server 8.1. For information about moving off Compatibility Security entirely, see Upgrading from Compatibility Security to WebLogic Server 8.1 Security.
CompatibilityRealm
) allows you to use the new security mechanisms available in WebLogic Server 8.1 while accessing the users and groups stored in a WebLogic Server 6.x LDAP, Windows NT, UNIX or RDBMS security realm.Note: You will not be able to access ACLs stored in a WebLogic Server 6.x security realm if you configure the Realm Adapter Authentication provider as an Authentication provider in a WebLogic Server 8.1 security realm. You will have to protect your application resources with security roles and security policies.
The following sections provide step-by-step instructions for upgrading your WebLogic Server 6.x security realms to version 8.1.
Note: Before following the instructions in this section, be sure to upgrade your WebLogic Server 6.x domain to version 8.1, using the instructions in Upgrading Your WebLogic Server 6.x Domain to Version 8.1.
This section provides step-by-step instructions for upgrading your WebLogic Server 6.x LDAP V2 security realm to a WebLogic Server 8.1 security realm. This upgrade causes the users and groups defined in your LDAP server to be referenced from the myrealm
security realm, which is the default (active) security realm in WebLogic Server 8.1.
Note: Security policies replace the access control lists (ACLs) and permissions that were used to protect WebLogic resources in WebLogic Server 6.x. Therefore, no ACLs will be referenced from the 8.1 security realm as a result of this upgrade. To learn about re-securing resources in WebLogic Server 8.1, see Verify the upgrade of ACLs by: and Securing WebLogic Resources.
To upgrade from a WebLogic Server 6.x LDAP V2 security realm to a WebLogic Server 8.1 security realm:
A list of currently defined users for the WebLogic Server 6.x LDAP V2 security realm appears at the bottom of the right pane. You will be referencing these users from the WebLogic Server 8.1 security realm.
A table of currently defined groups for the WebLogic Server 6.x LDAP V2 security realm appears in the right pane. You will be referencing these groups from the WebLogic Server 8.1 security realm.
The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the LDAP V2 security realm.
user.filter=(&(uid=%u)(objectclass=person))
user.dn=ou=people, ou=Test,dc=companysys,dc=com
server.port=1155
membership.filter=(&(uniquemember=%M)(objectclass=groupofuniquenames))
server.principal=uid=tadmin, ou=People,dc=companysys,dc=com
group.filter=(&(cn=%g)(objectclass=groupofuniquenames))
group.dn=ou=Groups,ou=Test,dc=companysys,dc=com
server.host=testmachine
Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.
mydomain
, by accepting most of the defaults.Note: Accept all the defaults in the Configuration Wizard to create the WebLogic Server 8.1 domain, with the exception of the username and password combination that is used to boot the server. This username and password combination must be in your LDAP server, and the user must be a member of the Administrators
group.
Step-by-step instructions for using the Configuration Wizard are in Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.
myrealm
The Authentication node expands to show the Authentication providers that have already been configured in the myrealm
security realm. By default, this includes the WebLogic security providers called DefaultAuthenticator
and DefaultIdentityAsserter
.
For example, if you have an iPlanet (Netscape) LDAP Server, click the Configure a New iPlantAuthenticator... link.
Note: If none of the Configure a New... links correspond to the type of LDAP server you have, see Accessing Other LDAP Servers in Managing WebLogic Security.
The Control Flag determines how this LDAP Authentication provider will be used in conjunction with other Authentication providers. Initially, the Control Flag is best left as OPTIONAL
. For more information, see Setting the JAAS Control Flag Attribute in Managing WebLogic Security.
Note: If you prefer, you can enter the values from the 6.x Caching realm you used with your WebLogic Server 6.x LDAP V2 security realm, instead of these defaults.
Warning: Do not yet restart the WebLogic Server 8.1 instance called myserver
, even if the restart icon is flashing.
User Base DN—the value of user.dn
User From Name Filter—the value of user.filter
(the default in the WebLogic Server 8.1 Administration Console may already be correct)
Note: Accept the defaults for other fields on the Users tab or fill in appropriate information.
Note: You are not required to set values for any fields on the Membership tab nor the Details tab. However, the WebLogic LDAP Authentication providers in WebLogic Server 8.1 have additional features available through these tabs, that you may want to take advantage of, such as dynamic groups. For more information about these features, see Configuring an LDAP Authentication Provider in Managing WebLogic Security.
Note: Because the config.xml.booted
file is a copy of the config.xml
that existed before you made any changes, saving it allows you to restore the old configuration in case you run into any problems.
myserver
by selecting Programs myrealm
.This section provides step-by-step instructions for upgrading your WebLogic Server 6.x Windows NT security realm to a WebLogic Server 8.1 security realm. This upgrade causes the users and groups defined in your Windows NT server to be referenced from the myrealm
security realm, which is the default (active) security realm in WebLogic Server 8.1.
Note: Security policies replace the access control lists (ACLs) and permissions that were used to protect WebLogic resources in WebLogic Server 6.x. Therefore, no ACLs will be referenced from the 8.1 security realm as a result of this upgrade. To learn about re-securing resources in WebLogic Server 8.1, see Verify the upgrade of ACLs by: and Securing WebLogic Resources.
To upgrade from a WebLogic Server 6.x Windows NT security realm to a WebLogic Server 8.1 security realm:
A list of currently defined users for the WebLogic Server 6.x Windows NT security realm appears at the bottom of the right pane. You will be referencing these users from the WebLogic Server 8.1 security realm.
A table of currently defined groups for the WebLogic Server 6.x Windows NT security realm appears in the right pane. You will be referencing these groups from the WebLogic Server 8.1 security realm.
The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the Windows NT security realm.
Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.
mydomain
, by accepting most of the defaults.Note: You can accept all the defaults in the Configuration Wizard to create the WebLogic Server 8.1 domain, with the exception of the username and password combination that is used to boot the server. This username and password combination must have the correct privileges to be able to restart the WebLogic Server 8.1 instance. (It need not be the Administrator account.)
Step-by-step instructions for using the Configuration Wizard are in Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.
Warning: If you do not use the Configuration Wizard to create your WebLogic Server 8.1 domain, you will not be able to create the Realm Adapter Authentication provider (in Step 2: Configure a Realm Adapter Authentication Provider) without first copying over your 6.x filerealm.properties
file.
Note: For a detailed explanation of the Realm Adapter Authentication provider, see Configuring a Realm Adapter Authentication Provider in Managing WebLogic Security.
myrealm
The Authentication node expands to show the Authentication providers that have already been configured in the myrealm
security realm. By default, this includes the WebLogic security providers called DefaultAuthenticator
and DefaultIdentityAsserter
.
The Control Flag determines how this Realm Adapter Authentication provider will be used in conjunction with other Authentication providers. Initially, the Control Flag is best left as OPTIONAL
. For more information, see Setting the JAAS Control Flag Attribute in Managing WebLogic Security.
The General tab updates to show a Types chooser, which allows you to select token types for an Authentication provider that includes an Identity Assertion provider.
Warning: Do not select any token types from the Types chooser. The WebLogic Authentication provider (called DefaultAuthenticator in the WebLogic Server 8.1 Administration Console) is already configured to handle a specified token type. The Realm Adapter Authenticator includes an Identity Assertion provider, which if configured to handle the same token type as the WebLogic Authentication provider, will render the server unbootable.
Note: Because the config.xml.booted
file is a copy of the config.xml
that existed before you made any changes, saving it allows you to restore the old configuration in case you run into any problems.
myserver
by selecting Programs The Compatibility Security node appears in the left pane of the WebLogic Server 8.1 Administration Console.
Re-configuring your WebLogic Server 6.x Windows NT realm in Compatibility security is what provides the connection to the Realm Adapter Authentication provider and allows you to view your 6.x users and groups in the WebLogic Server 8.1 Administration Console.
Note: Because the config.xml.booted
file is a copy of the config.xml
that existed before you made any changes, saving it allows you to restore the old configuration in case you run into any problems.
myserver
by selecting Programs This section provides step-by-step instructions for upgrading your WebLogic Server 6.x Unix security realm to a WebLogic Server 8.1 security realm. This upgrade causes the users and groups defined in your Unix server to be referenced from the myrealm
security realm, which is the default (active) security realm in WebLogic Server 8.1.
Note: Security policies replace the access control lists (ACLs) and permissions that were used to protect WebLogic resources in WebLogic Server 6.x. Therefore, no ACLs will be referenced from the WebLogic Server 8.1 security realm as a result of this upgrade. To learn about re-securing resources in WebLogic Server 8.1, see Verify the upgrade of ACLs by: and Securing WebLogic Resources.
To upgrade from a WebLogic Server 6.x Unix security realm to a WebLogic Server 8.1 security realm:
A list of currently defined users for the WebLogic Server 6.x Unix security realm appears at the bottom of the right pane. You will be referencing these users from the WebLogic Server 8.1 security realm.
A table of currently defined groups for the WebLogic Server 6.x Unix security realm appears in the right pane. You will be referencing these groups from the WebLogic Server 8.1 security realm.
The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the Unix security realm.
Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.
mydomain
, by accepting most of the defaults.Note: You can accept all the defaults in the Configuration Wizard to create the WebLogic Server 8.1 domain, but you must be logged into a Unix machine.
Step-by-step instructions for using the Configuration Wizard are in Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.
Warning: If you do not use the Configuration Wizard to create your WebLogic Server 8.1 domain, you will not be able to create the Realm Adapter Authentication provider (in Step 2: Configure a Realm Adapter Authentication Provider) without first copying over your 6.x filerealm.properties
file.
Note: For a detailed explanation of the Realm Adapter Authentication provider, see Configuring a Realm Adapter Authentication Provider in Managing WebLogic Security.
myrealm
The Authentication node expands to show the Authentication providers that have already been configured in the myrealm
security realm. By default, this includes the WebLogic security providers called DefaultAuthenticator
and DefaultIdentityAsserter
.
The Control Flag determines how this Realm Adapter Authentication provider will be used in conjunction with other Authentication providers. Initially, the Control Flag is best left as OPTIONAL
. For more information, see Setting the JAAS Control Flag Attribute in Managing WebLogic Security.
The General tab updates to show a Types chooser, which allows you to select token types for an Authentication provider that includes an Identity Assertion provider.
Warning: Do not select any token types from the Types chooser. The WebLogic Authentication provider (called DefaultAuthenticator in the WebLogic Server 8.1 Administration Console) is already configured to handle a specified token type. The Realm Adapter Authenticator includes an Identity Assertion provider, which if configured to handle the same token type, will render the server unbootable.
Note: Because the config.xml.booted
file is a copy of the config.xml
that existed before you made any changes, saving it allows you to restore the old configuration in case you run into any problems.
myserver
by selecting Programs The Compatibility Security node appears in the left pane of the WebLogic Server 8.1 Administration Console.
Re-configuring your Unix realm in Compatibility security is what provides the connection to the Realm Adapter Authentication provider and allows you to view your 6.x users and groups in the WebLogic Server 8.1 Administration Console.
Note: Because the config.xml.booted
file is a copy of the config.xml
that existed before you made any changes, saving it allows you to restore the old configuration in case you run into any problems.
Notes: The instructions in this section illustrate how to upgrade the RDBMS example that was provided with WebLogic Server 6.x. The RDBMS example utilized a Cloudscape database. Customers who have modified this example or use other databases may need to make some modifications to these instructions for their environment.
The instructions in this section provide step-by-step instructions for upgrading your WebLogic Server 6.x RDBMS security realm to a WebLogic Server 8.1 security realm. This upgrade causes the users and groups defined in your Cloudscape database to be referenced from the myrealm
security realm, which is the default (active) security realm in WebLogic Server 8.1.
Note: Security policies replace the access control lists (ACLs) and permissions that were used to protect WebLogic resources in WebLogic Server 6.x. Therefore, no ACLs will be referenced from the 8.1 security realm as a result of this upgrade. To learn about re-securing resources in WebLogic Server 8.1, see Securing WebLogic Resources.
To upgrade from a WebLogic Server 6.x RDBMS security realm to a WebLogic Server 8.1 security realm:
A list of currently defined users for the WebLogic Server 6.x RDBMS security realm appears at the bottom of the right pane. These are the users that will be referenced from the WebLogic Server 8.1 security realm.
A table of currently defined groups for the WebLogic Server 6.x RDBMS security realm appears in the right pane. These are the groups that will be referenced from the WebLogic Server 8.1 security realm.
The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the RDBMS security realms.
Note: The out-of-the-box RDBMS example used examples.security.rdbmsrealm.RDBMSRealm
as the value for the Realm Class.
Note: The out-of-the-box RDBMS example used COM.cloudscape.core.JDBCDriver
as the value for the Driver, and jdbc:cloudscape:demo;create=true;autocommit=false
as the value for the URL.
getGroupMembers=SELECT GM_GROUP, GM_MEMBER from groupmembers WHERE GM_GROUP = ? deleteGroup2=DELETE FROM aclentries WHERE A_PRINCIPAL = ? deleteGroup1=DELETE FROM groupmembers WHERE GM_GROUP = ? addGroupMember=INSERT INTO groupmembers VALUES ( ? , ? ) getUser=SELECT U_NAME, U_PASSWORD FROM users WHERE U_NAME = ? getPermission=SELECT DISTINCT A_PERMISSION FROM aclentries WHERE A_PERMISSION = ? deleteUser3=DELETE FROM aclentries WHERE A_PRINCIPAL = ? getGroupNewStatement=true deleteUser2=DELETE FROM groupmembers WHERE GM_MEMBER = ? deleteUser1=DELETE FROM users WHERE U_NAME = ? getAcls=SELECT A_NAME, A_PRINCIPAL, A_PERMISSION FROM aclentries ORDER BY A_NAME, A_PRINCIPAL getUsers=SELECT U_NAME, U_PASSWORD FROM users getGroups=SELECT GM_GROUP, GM_MEMBER FROM groupmembers getPermissions=SELECT DISTINCT A_PERMISSION FROM aclentries getAclEntries=SELECT A_NAME, A_PRINCIPAL, A_PERMISSION FROM aclentries WHERE A_NAME = ? ORDER BY A_PRINCIPAL newUser=INSERT INTO users VALUES ( ? , ? ) removeGroupMember=DELETE FROM groupmembers WHERE GM_GROUP = ? AND GM_MEMBER = ?
The RDBMS realm sample included in WebLogic Server 6.x at WL_HOME\samples\examples\security\rdbmsrealm
used a private Admin API (weblogic.management.Admin.getActiveDomain()
) in the RDBMSDelegate(RDBMSRealm realm)
method of the RDBMSDelegate.java
file. This private Admin API has been replaced with a public Admin API in WebLogic Server 8.1. Therefore, customers must:
RDBMSDelegate.java
file so that the RDBMS realm sample code uses the public Admin API rather than the private one. For more information, see MBean API Change. Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.
mydomain
, by accepting all of the defaults.For step-by-step instructions for the Configuration Wizard, see Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.
Note: For a detailed explanation of the Realm Adapter Authentication provider, see Configuring a Realm Adapter Authentication Provider in Managing WebLogic Security.
myrealm
The Authentication node expands to show the Authentication providers that have already been configured in the myrealm
security realm. By default, this includes the WebLogic security providers called DefaultAuthenticator
and DefaultIdentityAsserter
.
The Control Flag determines how this Realm Adapter Authentication provider will be used in conjunction with other Authentication providers. Initially, the Control Flag is best left as OPTIONAL
. For more information, see Setting the JAAS Control Flag Attribute in Managing WebLogic Security.
The General tab updates to show a Types chooser, which allows you to select token types for an Authentication provider that includes an Identity Assertion provider.
Warning: Do not select any token types from the Types chooser. The WebLogic Identity Assertion provider (called DefaultAuthenticator in the WebLogic Server 8.1 Administration Console) is already configured to handle a specified token type. The Realm Adapter Authenticator includes an Identity Assertion provider, which if configured to handle the same token type, will render the server unbootable.
cloudscape.jar
file, which is installed under WL_HOME\samples\eval\cloudscape\lib
.Note: Because the config.xml.booted
file is a copy of the config.xml
that existed before you made any changes, saving it allows you to restore the old configuration in case you run into any problems.
myserver
by selecting Programs The Compatibility Security node appears in the left pane of the WebLogic Server 8.1 Administration Console.
Re-configuring your RDBMS realm in Compatibility security is what provides the connection to the Realm Adapter Authentication provider and allows you to view your 6.x users and groups in the WebLogic Server 8.1 Administration Console.
myserver
by selecting Programs WebLogic Server 6.x Custom security realms can only be used in Compatibility security. The following list provides advice for common Custom security realm upgrade situations:
If your Custom security realm has a weblogic.properties
file rather than a config.xml
file, you will not be able to boot a WebLogic Server 8.1 instance in Compatibility security until you convert this file. For instructions on performing this conversion and more information about the conversion, see Converting the weblogic.properties File to .xml files and weblogic.properties Mapping Table in Migrating WebLogic Server 4.5 and 5.1 Applications to 6.x, respectively.
WebLogic Server 8.1 requires changes to WebLogic Server 5.x Custom realm code to make it compatible with WebLogic Server 6.x:
BasicRealm.getUser(String)
or BasicRealm.getUser(UserInfo)
method in your CustomRealm
class. This method should return null
for system
, everyone
and Administrators
. BasicRealm.getAcl()
method to ignore requests (that is, return null
) for ACL names starting with weblogic.server
. (For example, for an ACL name starting with weblogic.server.myserver
.) The return value of null
indicates to a WebLogic Server 6.x instance that it should boot by ignoring the ACLs that start with this prefix.Warning: Failure to meet the above requirements means that your server may not boot.
If you upgrade a WebLogic Server 6.x domain "in place" (that is, you use the same domain directory from 6.x and upgrade it to run under 8.1 by changing start scripts, classpaths, and so on described in Upgrading Your WebLogic Server 6.x Domain to Version 8.1, WebLogic Server 8.1 will automatically be configured for Compatibility security. If this describes your upgrade situation, the only steps necessary to complete your security upgrade are:
An example of instructions for these steps (using the RDBMS realm) are available in Step 2: Recompile the WebLogic Server 6.x RDBMS Realm Code for Use in WebLogic Server 8.1.
In WebLogic Server 6.x, an ACL defined the permissions by which a user could interact with a WebLogic resource. ACLs were used to protect both MBeans and other types of WebLogic resources. This section contains the following information about the state of ACLs:
ACLs on MBeans are not supported in WebLogic Server 8.1 and therefore cannot be upgraded to this version of WebLogic Server. ACLs on MBeans are replaced by security role protections. For information about MBean security role protections, see Protected MBean Attributes and Operations in Securing WebLogic Resources.
If you are running WebLogic Server 8.x in Compatibility security, any out-of-the-box ACLs that protected resources in WebLogic Server 6.x are represented by default security policies. If you have created additional ACLs (except those on MBeans), these will remain ACLs and continue to protect the WebLogic resource. In other words, when you run WebLogic Server 8.1 in Compatibility security, you may have a mixture of 6.x ACLs and 8.1 security roles/security policies. See Default Security Policies in Securing WebLogic Resources for more information.
Note: Be sure you have upgraded your WebLogic Server 6.x domain to a WebLogic Server 8.1 domain and have upgraded your WebLogic Server 6.x security realm to a WebLogic Server 8.1 security realm before following these instructions. For instructions, see Upgrading Your WebLogic Server 6.x Domain to Version 8.1 and Upgrading Your WebLogic Server 6.x Security Realms to 8.1.
myserver
by selecting Programs The Realm Adapter Authentication provider configured in Compatibility Security allows you to see the ACLs defined in WebLogic Server 6.x security configurations. However, it is important to understand that because out-of-the-box ACLs protecting WebLogic resources are no longer used in WebLogic Server 8.1, these ACLs are not being enforced.
For more information about WebLogic resources, see Types of WebLogic Resources in Securing WebLogic Resources.
If the ACL stated, for example, that the group Administrators
had permission to unlock servers, the Policy Statement on the Policy Editor page for ALL
the Server resource's methods would show: Caller is Granted the Role Admin
. This is because in WebLogic Server 8.1, the Administrators
group is granted the Admin
security role.
Note: All out-of-the-box ACLs protecting WebLogic resources are upgraded to security policies that use global roles. However, in WebLogic Server 8.1, there are also scoped roles, which you may find useful for securing your WebLogic resources. For more information, see Types of Security Roles: Global Roles and Scoped Roles in Securing WebLogic Resources.
Note: The ACLs and permissions that have been upgraded to Weblogic Server 8.x from WebLogic Server 6.x are those listed in the filerealm.properties
files from the examples
and petstore
domains. These are also listed in Listing 3-1 and Listing 3-2.
Listing 3-1 fileRealm.properties from 6.x examples Domain
acl.modify.weblogic.jndi.weblogic.fileSystem=everyone
user.j2ee=0xe22513c99d9279bdf9318894033ef310b9aa830f
acl.lookup.weblogic.jndi.weblogic.fileSystem=everyone
acl.lookup.weblogic.jndi.weblogic.ejb=system,everyone
acl.lookup.weblogic.jndi=system,everyone
acl.list.weblogic.jndi.weblogic.rmi=system,everyone
acl.lockServer.weblogic.admin=system,guest
acl.shutdown.weblogic.admin=system,guest
group.gold=
acl.boot.weblogic.server=system,everyone
user.jps_admin=0xcc0b7594b451623dd59a3db8148de6984c60ac74
acl.list.weblogic.jndi.weblogic.fileSystem=everyone
acl.lookup.weblogic.jndi.weblogic=system,everyone
acl.modify.weblogic.jndi.weblogic.rmi=system,everyone
acl.modify.weblogic.jndi.weblogic=system,everyone
acl.list.weblogic.jndi.weblogic=system,everyone
acl.lookup.weblogic.management=system,everyone
group.cust=j2ee
acl.modify.weblogic.management=system,everyone
acl.findMBeans.weblogic.admin=Administrators
group.Administrators=system
group.admin=jps_admin
acl.lookup.weblogic.jndi.weblogic.rmi=system,everyone
acl.list.weblogic.jndi=system,everyone
acl.modify.weblogic.admin.acl=system,guest
acl.list.weblogic.jndi.weblogic.ejb=system,everyone
acl.modify.weblogic.jndi=system,everyone
acl.write.managedObject=system,guest
acl.reserve.weblogic.jdbc.connectionPool.demopool=system,everyone
acl.read.managedObject=system,guest
acl.admin.weblogic.jdbc.connectionPoolcreate=system,guest
user.system=0xc4d441a2bdd9c4bba6029d63066781512326d355
acl.unlockServer.weblogic.admin=system,guest
acl.reset.weblogic.jdbc.connectionPool=system
acl.execute.weblogic.servlet=everyone
acl.modify.weblogic.jndi.weblogic.ejb=system,everyone
Listing 3-2 fileRealm.properties from 6.x petstore Domain
acl.modify.weblogic.jndi.weblogic.fileSystem=everyone
acl.lookup.weblogic.jndi.weblogic.fileSystem=everyone
user.support=0xa227185fac962e564de4796154a80757860e32d4
acl.lookup.weblogic.jndi.weblogic.ejb=system,newdbuSer,NEWDBUSER,everyone
acl.lookup.weblogic.jndi=system,newdbuSer,NEWDBUSER,everyone
acl.list.weblogic.jndi.weblogic.rmi=system,newdbuSer,NEWDBUSER,everyone
acl.create.weblogic.jms.ConnectionConsumer=guest
acl.lockServer.weblogic.admin=system,newdbuSer,NEWDBUSER,guest
acl.reserve.weblogic.jdbc.connectionPool.oraclepool=system,newdbuSer,NEWDBUSER,everyone
acl.shutdown.weblogic.admin=system,newdbuSer,NEWDBUSER,guest
acl.boot.weblogic.server=vlatas,system,newdbuSer,NEWDBUSER,everyone
acl.list.weblogic.jndi.weblogic.fileSystem=everyone
acl.lookup.weblogic.jndi.weblogic=system,newdbuSer,NEWDBUSER,everyone
acl.modify.weblogic.jndi.weblogic.rmi=system,newdbuSer,NEWDBUSER,everyone
acl.modify.weblogic.jndi.weblogic=system,newdbuSer,NEWDBUSER,everyone
acl.list.weblogic.jndi.weblogic=system,newdbuSer,NEWDBUSER,everyone
acl.lookup.weblogic.management=system,newdbuSer,NEWDBUSER,everyone
acl.modify.weblogic.management=system,newdbuSer,NEWDBUSER,everyone
acl.findMBeans.weblogic.admin=Administrators
group.Administrators=system
acl.lookup.weblogic.jndi.weblogic.rmi=system,newdbuSer,NEWDBUSER,everyone
acl.list.weblogic.jndi=system,newdbuSer,NEWDBUSER,everyone
acl.modify.weblogic.admin.acl=vlatas,system,newdbuSer,NEWDBUSER,guest
acl.list.weblogic.jndi.weblogic.ejb=system,newdbuSer,NEWDBUSER,everyone
acl.modify.weblogic.jndi=system,newdbuSer,NEWDBUSER,everyone
acl.frob.aclexample=joeuser
acl.write.managedObject=system,newdbuSer,NEWDBUSER,guest
acl.reserve.weblogic.jdbc.connectionPool.demopool=system,newdbuSer,NEWDBUSER,everyone
user.joeuser=0x5923f72dc88665f59c119a2a965897fc28a2feaa
acl.read.managedObject=system,newdbuSer,NEWDBUSER,guest
acl.admin.weblogic.jdbc.connectionPoolcreate=system,newdbuSer,NEWDBUSER,guest
user.system=0xfafe4ee933bf59e193de3a8a506a57ddd2364943
acl.unlockServer.weblogic.admin=system,newdbuSer,NEWDBUSER,guest
acl.reset.weblogic.jdbc.connectionPool=system
acl.execute.weblogic.servlet=everyone
acl.modify.weblogic.jndi.weblogic.ejb=system,newdbuSer,NEWDBUSER,everyone
If you want to leverage the new security features in WebLogic Server 8.1, you need to upgrade your existing security configuration to a WebLogic Server 8.1 security configuration.
When you boot your WebLogic Server 6.x configuration in WebLogic Server 8.1, a security realm called CompatibilityRealm
is created and set as the default (active) security realm. This Compatibility realm contains all your 6.x security data. In addition, a security realm called myrealm
is created when you boot WebLogic Server 8.1.
To upgrade from Compatibility security, you need to make the myrealm
security realm the default security realm:
The Realms table appears with two security realms configured. The two security realms are the CompatibilityRealm
and myrealm
. The CompatibilityRealm
will have the default attribute set to true
.
myrealm
. By default, the WebLogic security providers are configured in myrealm
. Administrators
group. This user replaces the system
user. To add a user to the Administrators
group: myrealm
as the default (active) security realm. For more information, see Setting a New Security Realm as the Default (Active) Security Realm in Managing WebLogic Security. In WebLogic Server 6.x, any unauthenticated user (anonymous user) was identified as a user called guest
. WebLogic Server allowed the guest
user access to WebLogic resources. Because of a potential security risk, the functionality was modified.
In this version of WebLogic Server, the guest
user is no longer supplied by default. WebLogic Server now distinguishes between the guest
user and an anonymous user by assigning an anonymous user the name <Anonymous>
.
If you want to use the guest
user as you did in WebLogic Server 6.x, do one of the following:
guest
user as the anonymous user in the WebLogic Authentication provider. (The WebLogic Authentication provider is already configured in the default security realm.) You do this by setting the following argument when starting a WebLogic Server instance: Caution: This argument was added to assist existing WebLogic Server customers to upgrade their security functionality. You should use great caution when using the guest
user in a production environment.
Previous releases of WebLogic Server supported the use of a password.ini
file for determining the administrative identity of a WebLogic Server deployment. The password.ini
file is no longer supported in WebLogic Server 8.1. It is replaced by the boot.properties
file, which contains your username and password in an encrypted format. For more information about using the boot.properties
file, see Boot Identity Files in the Administration Console Online Help. There is no direct upgrade of the old password.ini
file.
This section contains the following information about upgrading SSL:
Using files or the WebLogic Keystore provider as a way to store identity and trust is deprecated in WebLogic Server 8.1. Also, private keys stored in files may or may not be password protected. Private keys that are not password protected can be vulnerable to security attacks. BEA recommends upgrading to keystores as a way to store identity and trust. If you choose not to use a keystore, a password is required in order to use the private key and associated digital certificate with this release of WebLogic Server. For more information, see Configuring SSL in Managing WebLogic Security.
For the purpose of backward compatibility, the WebLogic Server 8.1 Administration Console provides mechanisms for configuring SSL using file-based identity and trust. However, you should upgrade to keystores as soon as possible.
By default in WebLogic Server 8.1, SSL clients check the trusted certificate authority of the server. This check is done whenever a client and server connect using SSL, including when WebLogic Server is acting as a client. The client rejects the server's trusted certificate authority if the certificate authority is not trusted by the client. Previous releases of WebLogic Server allowed you to store SSL client trust in a file. In WebLogic Server 8.1, a client's trusted CA certificates must be stored in a keystore. WebLogic Server 8.1 offers different keystore options for storing client trust.
By default, all the trusted certificate authorities available from the JDK (...\jre\lib\security\cacerts
) are trusted by SSL clients. Optionally, use the following command-line argument to specify a password for the JDK cacerts trust keystore:
-Dweblogic.security.JavaStandardTrustKeystorePassPhrase=
password
where password is the password for the Java Standard Trust keystore. This password is defined when the keystore is created.
You also have the option of specifying one of the following types of trust:
DemoTrust.jks
) located in the WL_HOME\server\lib
directory. In addition, the CAs in the JDK cacerts
keystore are trusted. To use the Demo Trust, specify the following command-line argument:-Dweblogic.security.TrustKeyStore=DemoTrust
Optionally, use the following command-line argument to specify a password for the JDK cacerts trust keystore:
-Dweblogic.security.JavaStandardTrustKeystorePassPhrase=
password
where password is the password for the Java Standard Trust keystore. This password is defined when the keystore is created.
weblogic.security.CustomTrustKeyStoreFileName=filename
This required command-line argument specifies the fully qualified path to the trust keystore
weblogic.security.CustomTrustKeystoreType=type
This optional command-line argument specifies the type of the keystore. Generally, this value for type is jks.
weblogic.security.CustomTrustKeystorePassPhrase=password
This optional command-line argument specifies the password defined when creating the keystore.
For more information about using keystores, see Configuring SSL in Managing Weblogic Security.
In this release of WebLogic Server, SSL clients perform a host name verification check by default. The SSL client compares the Common Name (CN) field in the digital certificate received from the server with the server name in the URL the client used to connect to the server. The CN field and the server name must match to pass the host name verification check. In previous releases of WebLogic Server, this check had to be enabled.
You may need to disable host name verification to ensure your SSL client continues to work properly. Note that disabling host name verification will make your environment vulnerable to man-in-the-middle attacks. To disable the check, specify the following command-line argument:
-Dweblogic.security.SSL.ignoreHostnameVerification=true
Note: If the SSL server specified an IP address in its URL, disable the host name verification check.
The SSL client can also use a custom host name verifier instead of the host name verifier supplied by WebLogic Server. A custom host name verifier is an implementation of the weblogic.security.SSL.HostnameVerifier
interface. Use the following command-line argument to specify a custom host name verifier:
-Dweblogic.security.SSL.hostnameVerifier=
classname
where classname
specifies the implementation of the weblogic.security.SSL.HostnameVerifier
interface.
If your WebLogic Server 6.x security configuration used an implementation of the weblogic.security.acl.CertAuthenticator
class, you need to configure the Realm Adapter Authentication provider's included Identity Assertion provider.
To enable identity assertion in the Realm Adapter Authentication provider:
When the Identity Assertion provider is configured, the Cert Authenticator is called before any username/password authentication. This change in behavior may cause a Cert Authenticator written in WebLogic Server 6.x to fail if clients use both two-way SSL and username and password for authentication. To fix this problem, configure the Cert Authenticator in the Realm Adapter Authentication provider to return NULL
for unrecognized certificates or for all certificates if certificates are being used to establish the SSL connection.
You can still use private keys and digital certificates used with WebLogic Server 6.1 with WebLogic Server 8.1. Convert the private key and digital certificate from privacy-enhanced mail (PEM) format to distinguished encoding rules (DER) format. For more information, see the description of the der2pem utility in Using WebLogic Server Java Utilities.
After converting the files, ensure the digital certificate file has the -----BEGIN CERTIFICATE----
header and the -----END CERTIFICATE-----
footer. Otherwise, the digital certificate will not work with WebLogic Server 8.1.
The following sections provide additional information that may be useful about deprecated features, upgrades, and the important changes that have been made in WebLogic Server 8.1.
Note: WebLogic Server 8.1 uses PointBase 4.2 as a sample database and does not bundle the Cloudscape database.
The built-in transformer in WebLogic Server 8.1 is based on the Apache Xalan 2.2 transformer.
Use of the Xalan APIs directly has been deprecated. If you are still using those APIs and encounter difficulties, you should use the Java API for XML Processing (JAXP) to use XSLT.
Changes were made to Apache's Xalan code to enable Xerces and Xalan to work together. You may encounter problems if you use Xalan from Apache, because it will not include these changes.
In general, it is best to use JAXP and to port any vendor-specific code to a neutral API such as JAXP for SAX, DOM, and XSL processing.
Previous versions of WebLogic Server included the unmodified versions of the Xerces parser and Xalan transformer from www.apache.org in the WL_HOME
\server\ext\xmlx.zip
file. The ZIP file no longer includes these classes and interfaces. Download the unmodified Xerces parser and Xalan transformer directly from the Apache Web site.
The built-in XML parser for WebLogic Server 8.1 is based on the Apache Xerces 1.4.4 parser. The parser implements version 2 of the SAX and DOM interfaces. Users who used older parsers that were shipped in previous versions may receive deprecation messages.
WebLogic Server 8.1 also includes the WebLogic FastParser, a high-performance XML parser specifically designed for processing small-to-medium-size documents, such as SOAP and WSDL files associated with WebLogic Web services. Configure WebLogic Server to use FastParser if your application handles mostly small to medium size (up to 10,000 elements) XML documents. For more information, see Administering WebLogic Server XML in Programming WebLogic Server XML.
Previous versions of WebLogic Server included the unmodified versions of the Xerces parser and Xalan transformer from www.apache.org in the WL_HOME
\server\ext\xmlx.zip
file. The ZIP file no longer includes these classes and interfaces.
In WebLogic Server 6.1, 7.0, and 8.1 there is a division between runtime modes. The two modes are "development" and "production." The runtime mode with a command- line parameter when starting the Weblogic Server (-Dweblogic.ProductionModeEnabled=true | false
). If this parameter is set to true, the server runs in development mode. In development mode the server behavior is consistent with WebLogic Server 6.0. In production mode in versions 6.1 and later, however, the auto-deployment feature is disabled, with the result that deployment units in the applications directory that are not explicitly deployed in the configuration repository (config.xml
) will not be automatically deployed.
WebLogic Server 8.1 uses a two-phase deployment model that fails a clustered deployment on all servers if it fails on some servers. For more information on this deployment model and other 8.1 deployment features, see Deploying WebLogic Server Applications. By default, statically configured applications use the 6.x deployment model. Deployments initiated through the console or the new weblogic.Deployer
command line utility use the new two-phase deployment model.
Unlike previous versions, WebLogic Server 8.1 will not deploy an application that has any errors in its deployment descriptor. For example, if your WebLogic Server 6.x application was missing a reference description stanza in the deployment descriptor, the application will not deploy in WebLogic Server 8.1 until you add that stanza. A typical stanza looks like this:
<ejb-reference-description>
<ejb-ref-name>ejb/acc/Acc</ejb-ref-name>
<jndi-name>estore/account</jndi-name>
</ejb-reference-description>
Using WebLogic Server 8.1, you can no longer deploy through the console using the 6.x protocol. As a result, you must use the new deployment APIs. If your application is previously deployed in 6.x and you are starting your server, the applications are deployed with one-phase deployment. The weblogic.deploy
and weblogic.refresh
command line utilities and the weblogic.management.tools.WebAppComponentRefreshTool
and are deprecated in 8.1.
See Deprecated APIs and Features for information on deprecated MBean attributes and operations.
The EJB 2.0 specification has changed substantially between WebLogic Server 6.0 and WebLogic Server 8.1, and somewhat between WebLogic Server 6.1 and WebLogic Server 8.1.
Some of the prominent changes are listed here. To see a complete listing of the specification changes from WebLogic Server 6.0 to WebLogic Server 8.1, you can view and download the EJB 2.0 final specification at http://java.sun.com/products/ejb/2.0.html.
For more information about the changes between WebLogic Server 6.0 and WebLogic Server 6.1, see EJB Enhancements in WebLogic Server in Introducing WebLogic Server Enterprise JavaBeans in the WebLogic Server 6.1 documentation. EJB 1.1 beans that worked in WebLogic Server 6.x should work just as well in WebLogic Server 8.1 with no alteration.
You may have to make the following changes to EJB 2.0 beans:
relationship-role-source
. In 6.0, the element name was role-source
.destination-type
. In 6.0, the element name was jms-destination-type
.run-as
. In 6.0, the element name was run-as-specified-identity
.EJB-QL
queries require a SELECT
clause.abstract-schema-name
element specified in their ejb-jar.xml
in WebLogic Server 8.1.Other major changes that resulted from the EJB 2.0 specification changes are as follows:
NOT_SUPPORTED
for a transaction attribute. It also doesn't do exclusive locking, but gives each transaction its own instance of the read-only bean to use.EJB QL
query without using a qualified path. However, as of the final specification, all EJB QL
queries must have a qualified path.NOT_SUPPORTED
for a transaction attribute. The new implementation also does not do exclusive locking, but gives each transaction its own instance of the read-only bean to use.If you have trouble with a servlet within the scope of application deployment see Deployment.
Beginning in Weblogic Server 6.1 and continuing in WebLogic Server 8.1, the interface weblogic.management.configuration.EJBComponentMBean
changed so that it extends both ComponentMBean and EJBContainerMBean. Any methods that implement EJBComponentMBean (for example, getVerboseEJBDeploymentEnabled) must be changed to support EJBContainerMBean when you upgrade from WebLogic Server 6.0 to 8.1.
In WebLogic Server 8.1 the max-beans-in-cache
parameter controls the maximum number of beans in the cache for Database concurrency. In earlier WebLogic Server versions, max-beans-in-cache
was ignored; the size of the cache was unlimited. You may need to increase the size of this parameter.
Note: Evaluate the amount of memory available with the amount you require as, assigning a very high value to the max-beans-in-cache parameter may result in an OutOfMemoryError. The amount of memory cache required can be calculated as the number of beans in the cache times the size of the EJB.
In an EJB QL Query on WebLogic Server 8.1, all path-expressions must be fully qualified. This is a change from WebLogic Server 6.x. If you see an ejbc error while running ejbc on WebLogic Server 8.1 using a 6.x EJB, you need to correct either your ejb-ql
elements in your ejb-jar.xml
file or your weblogic-ql
elements in your weblogic-cmp-jar.xml
file. For example:
SELECT address FROM CustomerBean AS c WHERE zip = ?1
SELECT c.address FROM CustomerBean AS c WHERE c.zip = ?1
For information about upgrading from WebLogic jCOM 6.1 to WebLogic jCOM 8.1 see Upgrading Considerations in Programming WebLogic jCOM.
The minimum capacity increment for a JDBC connection pool has changed from 0, in WebLogic Server 6.1, to 1, in version 8.1. See JDBCConnectionPool in WebLogic Server Configuration Reference.
If you compile your application in WebLogic Server 8.1, it is advisable to do subsequent builds referencing JDK 1.4 rather than earlier JDKs.
JDK 1.4 requires stricter adherence to specifications than did earlier JDKs. For example, the Blueprint example application Pet Store contains methods that declare int
while their setters specify String
. These methods were acceptable in earlier versions of WebLogic Server, but they need to be repaired before they can run in WebLogic Server 8.1, because JDK 1.4 disallows them. See Fix JSP Parsing Errors.
Improper code that was acceptable under JDKs before 1.3.1_09 may cause errors under JDK 1.3.1_09 and later. This failure occurs for JSPs and all beans that are subject to the Introspector API. Specifically, disagreement between a property's setter and getter types may cause startup errors like the following after you migrate to JDK 1.3.1_09 or later:
Error in using tag library uri='/WEB-INF/tlds/taglib.tld' prefix='j2ee': There is no setter method for property 'numItems', for Tag class 'com.sun.j2ee.blueprints.petstore.taglib.list.SearchListTag' probably occurred due to an error in /template.jsp line 8: <%@ taglib uri="/WEB-INF/tlds/taglib.tld" prefix="j2ee" %>
When a class fails conform to Java bean specifications about type agreement, the java.beans.Introspector
API no longer returns read or write methods for the offending property. Correct such errors by ensuring that the setters and getters in your classes do not disagree in type. If the setter is an integer, the getter must be an integer also, and must not be a string.
For example, the following snippet shows a valid setter and getter from which we can expect the Introspection API to return valid read and write method(s):
private String foo;
public void setFoo(String f) {
foo = f;
}
public String getFoo() {
return foo;
}
The following snippet demonstrates bad code that does not conform to Java bean specifications:
private int foo; // note that foo is an int
public void setFoo(String f) {
foo = Integer.parseInt(f);
}
public int getFoo() {
return foo;
}
In the second case, the type disagreement between the setter and getter will cause an error under JDK 1.3.1_09 and later, because the newer JDKs adhere strictly to the Java bean specifications. */
Some APIs and other items added in JDK 1.4 have been removed in the WebLogic Server 8.1 version of weblogic.jar
. Such APIs and other items cease to be available to your application in WebLogic Server 8.1 after you compile your application with the 8.1 weblogic.jar
in place of the earlier version of weblogic.jar
in your classpath.
JAXP, for example, was included in previous versions of weblogic.jar
, but is absent from the WebLogic Server 8.1 weblogic.jar
. JAXP is not in the JDK 1.3, so if your WebLogic Server 6.x application uses JAXP and you compile it after replacing the 6.x weblogic.jar
with the 8.1 weblogic.jar
, build your classes using the JDK 1.4.
Other WebLogic Server 8.1 dependencies on JDK 1.4 include the JAAS package and the Principal Authenticator object.
WebLogic Server 8.1 supports the JavaSoft JMS specification version 1.0.2.
All WebLogic JMS 6.x applications are supported in WebLogic JMS 8.1. However, in order for your applications to use the new highly available JMS features, you will need to configure your existing physical destinations (queues and topics) to be part of a single distributed destination set. For more information on using JMS distributed destinations, see Using Distributed Destinations in Programming WebLogic JMS.
For more information on porting your WebLogic JMS applications, see Porting WebLogic JMS Applications in Programming WebLogic JMS.
All public WebLogic Server 6.x MBeans and attributes are supported in WebLogic Server 8.1. However, if you are employing internal MBeans or attributes, you may encounter porting issues.
See Deprecated APIs and Features for information on deprecated MBean attributes and operations.
Jolt users may need to upgrade to Jolt Java Client 8.1.0 to enable BEA Tuxedo services for the Web using BEA WebLogic Server 8.1. For more information, see Platform Support for Jolt. The Jolt Java Client is available from the BEA Product Download Center.
When you upgrade a domain to WebLogic Server 8.1, consider upgrading your JVM to JRockit. WebLogic JRockit is a JVM designed for running server-side applications in Windows and Linux running on Intel architectures. For server-side applications, JRockit has these advantages over other virtual machines:
To switch a WebLogic Server domain to the JRockit JVM:
JAVA_HOME
(or equivalent) shell variables to point to the JRockit root directory. For example, change:@rem Set user-defined variables.
set JAVA_HOME=WL_HOME\jdk131
where WL_HOME
is the WebLogic Server 6.x installation directory, to
@rem Set user-defined variables.
set JAVA_HOME=WL_HOME\jrockit81_141_02
where WL_HOME
is the WebLogic Server 8.1 installation directory.
JavaCompiler="WL_HOME\jdk131\bin\javac"
where WL_HOME
is the WebLogic Server 6.x installation directory, to
JavaCompiler=WL_HOME\jrockit81_141_02\bin\javac"
where WL_HOME
is the WebLogic Server 8.1 installation directory.
echo on "%JAVA_HOME%\bin\java" -hotspot .... weblogic.Server
For JRockit platform and user information, see the appropriate version of the JRockit User Guide.
Due to a change in the JSP specification, null request attributes now return the string "null" instead of an empty string. WebLogic Server versions since 6.1 contain a new flag in weblogic.xml
called printNulls
which is true by default, meaning that returning "null" is the default. Setting printNulls
to false ensures that expressions with "null" results are printed as an empty string, not the string "null."
An example of configuring the printNulls element in weblogic.xml :
<param-name>printNulls</param-name>
<param-value>false</param-value>
The behavior of the load order methods in StartupClassMbean
has changed between versions 6.x and 8.1.
If you set load order in version 6.x by setting LoadBeforeAppDeployment
to true or false, you should now use LoadBeforeAppActivation
.
In 6.x, setting LoadBeforeAppDeployments
to true caused startup classes to be invoked after the datasources were created and before the applications were activated. In version 8.1, achieve the same load order by setting LoadBeforeAppActivation
to true.
LoadBeforeAppDeployments
still exists in version 8.1 but its behavior has changed. It now determines whether a startup class is loaded and run before the server activates JMS and JDBC services or deploys applications and EJBs.
See details about these methods in version 8.1 at ../javadocs/weblogic/management/configuration/StartupClassMBean.html.
A Managed Server running WebLogic Server 6.x cannot obtain its configuration and boot using an Administration Server running WebLogic Server 8.1. Make sure that you do not copy the running-managed-servers.xml
file from your WebLogic Server 6.x installation directory to your WebLogic Server 8.1 installation directory.
Default names for execute queues have changed in WebLogic Server 8.1. If you upgrade a configuration that specifies execute queues, the default queue names will automatically alias the new queue names.
Previous versions of this document and various other sample documents erroneously described using weblogic.management.Admin.getInstance().getAdminMBeanHome()
as a way to look up the MBeanHome
interface on the Administration Server.
However, the weblogic.management.Admin
class is not public. Instead of using this non-public class, use JNDI to retrieve MBeanHome
. See Determining the Active Domain and Servers in Programming WebLogic Server JMX Services.
For servlets, update your web.xml
file so that it uses the following new classes:
weblogic.servlet.proxy.HttpClusterServlet
weblogic.servlet.internal.HttpClusterServlet
weblogic.servlet.proxy.HttpProxyServlet
weblogic.t3.srvr.HttpProxyServlet
If you have trouble with a servlet within the scope of application deployment see Deployment.
In WebLogic Server 6.0, the number of worker threads was specified via the ThreadPoolSize
parameter on the Server MBean. Starting in WebLogic Server 6.1, the number of worker threads is defined via an ExecuteQueue
on the Server MBean.
WebLogic Server 8.1 provides a porting path for this parameter, so that if it is specified in the config.xml
file, or if it is passed to the client or server on the command line (-Dweblogic.ThreadPoolSize=<xx>
), WebLogic Server ports your ThreadPoolSize
to the ThreadCount
setting automatically.
In WebLogic Server 6.x you set the thread count on the command line as follows:
<Server
Name="myserver"
ThreadPoolSize="23"
...
/Server>
Starting in WebLogic Server 7.0 you set the thread count on the command line as follows:
<Server
Name="myserver"
... >
<ExecuteQueue
Name="default"
ThreadCount="23" />
/Server>
To change the thread count value via the Administration Console in WebLogic Server 8.1:
Previous versions of WebLogic Server resolved URIs that contained extra spaces. WebLogic Server 8.1 no longer resolves extra spaces, and a URI request that contains extra spaces will result in a 404.
For example, http://server:port/mywebapp/foo%20%20
used to resolve to the resource foo
in the Web application "mywebapp," but beginning with 8.1 it no longer does.
weblogic.management.runtime.ServletRuntimeMBean.getName()
API (in WebLogic Server 6.0) has changed to weblogic.management.runtime.ServletRuntimeMBean.getServletName()
in WebLogic Server 6.1 and 7.0 and 8.1. You will have to update your source code and recompile if you are using weblogic.management.runtime.ServletRuntimeMBean.getName()
. context-root
element in the application's application.xml
file, if the application is part of an enterprise application, or the weblogic.xml
file if it is a standalone Web application, to "/". <check-auth-on-forward>
to the weblogic.xml
file. Certain applications (large EJB applications) deployed in a WebLogic Server cluster on Solaris will perform better using the client JVM rather than the server JVM. This is especially true under heavy loads.
You must make the following application and configuration changes to use WebLogic Tuxedo Connector in WebLogic Server 8.1:
Note: For more information on how to configure WebLogic Tuxedo Connector, see Configuring WebLogic Tuxedo Connector Using the Administration Console.
Releases prior to WebLogic Server 7.0 use a WebLogic Server Startup class to start a WebLogic Tuxedo Connector session and a WebLogic Server Shutdown class to end a session. In WebLogic Server 8.1, WebLogic Tuxedo Connector is managed as a WebLogic Server Service.
For more information on starting and ending a WebLogic Tuxedo Connector session, see Assign a WTC Service to a Server.
In 8.1, WebLogic Tuxedo Connector is implemented as a service and no longer utilizes a separate XML configuration file. The WTCMigrateCF
tool migrates XML configuration file information into the config.xml
file of an active Administration server. Use the following steps to convert your pre-8.1 WebLogic Tuxedo Connector XML configuration file:
java
-Dweblogic.wtc.migrateDebug
weblogic.wtc.gwt.WTCMigrateCF-url
URL-username
USERNAME-password
PASSWORD-infile
CONFIGWTC
[-server SERVERNAME] [-domain DOMAIN] [-protocol PROTOCOL]
[-deploy]
The arguments for this command are defined as follows:
When the migration is complete, the migration utility displays:
The information from the specified XML configuration file is migrated and placed in the config.xml
file of the server specified in step 2. The migration utility sets the AppKey Generator attribute to TpUsrFile
and the Default AppKey attribute to -1.
For more information on how to use inbound RMI-IIOP with the WebLogic Tuxedo Connector, see Using WebLogic Tuxedo Connector for RMI-IIORP.
To use inbound RMI-IIOP in 8.1, you must modify the reference object that connects WebLogic Tuxedo Connector instances to Tuxedo CORBA applications. Tuxedo CORBA objects now use the server name to reference remote WebLogic Tuxedo Connector objects. Earlier releases used the DOMAINID
.
Listing 3-3 Domain Configuration File
*DM_RESOURCES
VERSION=U22*DM_LOCAL_DOMAINS
TDOM1 GWGRP=SYS_GRP
TYPE=TDOMAIN
DOMAINID="TDOM1"
BLOCKTIME=20
MAXDATALEN=56
MAXRDOM=89*DM_REMOTE_DOMAINS
TDOM2 TYPE=TDOMAIN
DOMAINID="TDOM2"*DM_TDOMAIN
TDOM1 NWADDR="<network address of Tuxedo domain:port>"
TDOM2 NWADDR="<network address of WTC domain:port>"*DM_REMOTE_SERVICES
//
"servername
"
You are now ready to start your applications.
For more information, see User Authentication.
WebLogic Tuxedo Connector uses Access Control Lists (ACLs) limit the access to local services within a local domain by restricting the remote domains that can execute these services. The valid values for this parameter are:
If the WebLogic Tuxedo Connector ACL Policy is set to Local
, the Tuxedo remote domain DOMAINID
must be authenticated as a local user. To allow WebLogic Tuxedo Connector to authenticate a DOMAINID
as a local user, use the WebLogic Server 8.1 Administration Console to complete the following steps:
If the WebLogic Tuxedo Connector ACL Policy is GLOBAL
, the user's security token is passed. No administration changes are required.
Note: For more information on how to set WebLogic Tuxedo Connector properties, see How to Set WebLogic Tuxedo Connector Properties.
TraceLevel and PasswordKey are now WebLogic Server properties.
To monitor the WebLogic Tuxedo Connector using the WebLogic Server log file, you must set the tracing level using the WebLogic Server TraceLevel property. For more information, see Monitoring the WebLogic Tuxedo Connector .
To generate passwords using the weblogic.wtc.gwt.genpasswd utility, you must set a password key using the WebLogic Server PasswordKey property. For more information on how to generate passwords, see Configuring a WTCPassword MBean .
This release of WebLogic Tuxedo Connector implements a new WTC ORB which uses WebLogic Server RMI-IIOP runtime and CORBA support. Previous releases used a JDK based WTC ORB. A wrapper is provided to allow users with legacy applications to use the new WTC ORB without modifying their existing applicatons. BEA recommends that users migrate to the new WTC ORB. For more information, see How to Develop WebLogic Tuxedo Connector Client Beans using the CORBA Java API.
Due to changes in the Web service runtime system and architecture between versions 6.1 and 8.1 of WebLogic Server, you must upgrade Web services created in version 6.1 to run on version 8.1.
The WebLogic Web services client API included in WebLogic Server 6.1 of has been deprecated and you cannot use it to invoke 8.1 Web services. WebLogic Server 8.1 includes a new client API, based on the Java API for XML-based RPC (JAX-RPC).
For detailed information on upgrading a 6.1 WebLogic Web service to 8.1, see Upgrading 6.1 WebLogic Web Services to 8.1.
For examples of using JAX-RPC to invoke WebLogic Web services, see Invoking Web Services.
For general information on the differences between 6.1 and 8.1 Web services, see Overview of WebLogic Web Services.
weblogic.deploy
is deprecated in this release of WebLogic Server 8.1 and has been replaced by weblogic.Deployer
. For more information, see Deploying WebLogic Server Applications.weblogic.management.tools.WebAppComponentRefreshTool
and weblogic.refresh
are both deprecated in this release of WebLogic Server 8.1. They have been replaced by weblogic.Deployer
.weblogic.Admin
command in order to create application and component MBeans, set the attributes on the MBeans, and invoke operations on those MBeans to cause them to get deployed in the system, the following MBean attributes and operations have been deprecated:Deprecated ApplicationMBean
operations:
deploy
load
undeploy
Deprecated ApplicationMBean
attributes:
LastModified
LoadError
isDeployed
Please refer to the WebLogic Server 8.1 javadocs for the ApplicationMBean
interface to see what has replaced these attributes and operations.
WebLogic Enterprise Connectivity (WLEC) examples have been removed.