Upgrading WebLogic Server 6.x to Version 8.1

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:

• Contents of a Domain Directory
• Understanding the WebLogic Server 8.1 Directory Structure
• Upgrading Your WebLogic Server 6.x Domain to Version 8.1
• Modifying Start Scripts
• Upgrading the Pet Store Application from WebLogic Server 6.1 Service Pack 4 to WebLogic Server 8.1
• Upgrading WebLogic Server 6.x Security to Version 8.1
• Additional Upgrade Procedures and Information

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.

 

---

Understanding the WebLogic Server 8.1 Directory Structure

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.

 

---

Contents of a Domain Directory

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:

• The configuration file (config.xml) for the domain.
• Any scripts you use to start server instances and establish your environment.
• Optionally, a subdirectory for storing the domain's application files.

For more information about WebLogic Server domains, see WebLogic Server Domains in Configuring and Managing WebLogic Server.

 

---

Upgrading Your WebLogic Server 6.x Domain to Version 8.1

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 the Installation Guide for installation instructions for WebLogic Server 8.1.

• Shut Down WebLogic 6.x Server Instances
• Create a WebLogic Server 8.1 Domain Directory
• Copy Contents of Your 6.x Domain into the 8.1 Directory
• Delete WebLogic Server 6.x Settings from the 8.1 Domain
• Modify Server Start Scripts
• Upgrade Applications
• Start 8.1 Administration and Managed Servers
• Configure and Deploy Your Applications

 

Shut Down WebLogic 6.x Server Instances

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 WebLogic Server 8.1 Domain Directory

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 Contents of Your 6.x Domain into the 8.1 Directory

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.

 

Delete WebLogic Server 6.x Settings from the 8.1 Domain

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 Server Start Scripts

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 Applications

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.

1. Make the relative paths in the application's deployment descriptor files point to the actual locations of any external files they reference, in case the location of the external files relative to the application has changed.

   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:

   • Re-create the directory locations of the external files relative to the new locations of the files that reference them
   • Edit the references to the actual locations of the files.
2. To update utilities such as the Java compiler, use the WebLogic Server 8.1 Administration Console to configure the appropriate attribute to use the new file or utility.
3. Consider upgrading your JVM to JRockit. See Upgrading Your JVM to JRockit.
4. If you are upgrading EJBs from WebLogic Server 6.0, you may have to make manual changes as described inManual Changes to Deployment Descriptors for EJB 2.0.
5. Your application may require additional upgrade steps to account for other factors, for example new parsers and altered APIs. See Additional Upgrade Procedures and Information for information about these factors.
6. For instructions on configuring security in WebLogic Server 8.1, see Upgrading WebLogic Server 6.x Security to Version 8.1.

 

Start 8.1 Administration and Managed Servers

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.

 

Configure and Deploy Your Applications

For information about configuring and deploying your applications, see Deployment.

 

---

Modifying Start Scripts

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:

• Shut down your server instance
• Copied your domain to a new location

To modify a start script:

1. Remove or comment out the JAVA_HOME setting.

   For example, remove:

   set JAVA_HOME=C:\bea61\jdk131

   The JAVA_HOME variable is defined elsewhere (in the commEnv.cmd script).

2. Remove the lines that specify the JDK and the startWebLogic.cmd (or .sh) if they are present.

   Remove:

   @rem Check that script is being run from the appropriate directory

   if not exist lib\weblogic.jar goto wrongplace

   goto checkJDK

   :wrongplace

   echo startWebLogic.cmd must be run from the config\mydomain directory. 1>&2

   goto finish

   :checkJDK

   if exist "%JAVA_HOME%/bin/javac.exe" goto runWebLogic

   echo.

   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.

   goto finish

3. Change the PATH setting.

   Remove the reference to .\bin.

   set PATH=.\bin;%PATH%

4. Remove the CLASSPATH setting.

   set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar

5. Add the following lines:

   set WL_HOME=(the WebLogic Server 8.1 installation directory)

   call %WL_HOME%\common\bin\commEnv.cmd

   set CLASSPATH=%WEBLOGIC_CLASSPATH%;%CLASSPATH%

6. In the start command line (the line that ends with "weblogic.Server"), remove the reference to bea.home (for instance, "-Dbea.home=C:\bea61")

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.

 

---

Upgrading the Pet Store Application from WebLogic Server 6.1 Service Pack 4 to WebLogic Server 8.1

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.

 

Repair Pet Store

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:

• Fix Erroneous <ejb-ref-name>
• Add Missing <ejb-ref-name>
• Fix Encoding Error
• Clean fileRealm.properties
• Fix JSP Parsing Errors
• Rebuild Petstore

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.

 

Fix Erroneous <ejb-ref-name>

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.

1. In a command console or file browser, navigate to WL_HOME\samples\petStore\src\components\customer\src. For example:

   C:\> cd WL_HOME\samples\petStore\src\components\customer\src

2. Open customer_weblogic_ejb.xml in a text editor. For example:

   WL_HOME\samples\petStore\src\components\customer\src> notepad customer_weblogic_ejb.xml

3. In customer_weblogic_ejb.xml, add the text bolded below.

   <ejb-name>TheCustomer</ejb-name>
   

   <reference-descriptor>
   

   <ejb-reference-description>
   

   <ejb-ref-name>ejb/account/Account</ejb-ref-name>
   

   <jndi-name>estore/account</jndi-name>
   

   </ejb-reference-description>
   

   <ejb-reference-description>
   

   <ejb-ref-name>ejb/order/Order</ejb-ref-name>
   

   <jndi-name>estore/order</jndi-name>
   

   </ejb-reference-description>
   

   </reference-descriptor>
   

   <jndi-name>estore/customer</jndi-name>
   

4. Add the bolded text in the following:

<ejb-name>TheOrder</ejb-name>

<reference-descriptor>

<resource-description>

<res-ref-name>jdbc/EstoreDataSource</res-ref-name>

<jndi-name>jdbc.EstoreDB</jndi-name>

</resource-description>

<ejb-reference-description>

<ejb-ref-name>ejb/account/Account</ejb-ref-name>

<jndi-name>estore/account</jndi-name>

</ejb-reference-description>

</reference-descriptor>

<jndi-name>estore/order</jndi-name>

1. Save and close customer_weblogic_ejb.xml.

 

Add Missing <ejb-ref-name>

1. In a command console, navigate to WL_HOME\samples\petStore\src\petstore\src\docroot\WEB-INF, where WL_HOME is the WebLogic Server 6.1 installation directory. For example:

   C:\> cd WL_HOME\samples\petStore\src\petstore\src\docroot\WEB-INF

2. Open weblogic.xml in a text editor. For example:

   WL_HOME\samples\petStore\src\petstore\src\docroot\WEB-INF>notepad weblogic.xml

3. 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>
   

4. Save and close weblogic.xml.

 

Fix Encoding Error

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.

1. In a command console, navigate to WL_HOME\samples\petStore\src\petstore\src\docroot\WEB-INF\xml\ja. For example:

   C:\>cd WL_HOME\samples\petStore\src\petstore\src\docroot\WEB-INF\xml\ja

2. Open screendefinitions.xml in a text editor. For example:

   WL_HOME\samples\petStore\src\petstore\src\docroot\WEB-INF\xml\ja> notepad screendefinitions.xml

3. Change the encoding in screendefinitions.xml from Unicode to utf-16.

   <?xml version="1.0" encoding="Unicode"?>

   becomes:

   <?xml version="1.0" encoding="utf-16"?>

4. Save and close screendefinitions.xml.

 

Clean fileRealm.properties

Delete a wildcard setting from a Pet Store property file because it may cause a security error.

1. In a command console, navigate to WL_HOME\config\petstore.
2. Open fileRealm.properties in a text editor. For example:

   WL_HOME\config\petstore>notepad fileRealm.properties
   

3. Locate and delete this line:

   acl.reset.weblogic.jdbc.connectionPool=system
   

 

Fix JSP Parsing Errors

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:

1. In a command console, navigate to WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list. For example:

   C:\> cd WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list

2. Open ListTag.java in a text editor. For example:

   WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list>notepad ListTag.java.

3. Change:

   public void setNumItems(String numItemsStr) {
   

   numItems = Integer.parseInt(numItemsStr);

   }

   to:

   public void setNumItems(int numItemsIn) {
   

   numItems = numItemsIn;
   

   }
   

4. Change:

   public void setStartIndex(String startIndexStr) {
   

   startIndex = Integer.parseInt(startIndexStr);
   

   }
   

   to:

   public void setStartIndex(int startIndexIn) {
   

   startIndex = startIndexIn;
   

   }
   

5. Save and close ListTag.java.

Make the replacements in the rest of the files as follows:

1. In the command console, navigate to WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list. For example:

   C:\>cd WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list

2. Open CartListTag.java in a text editor. For example:

   WL_HOME\samples\petStore\src\petstore\src\com\sun\j2ee\blueprints\petstore\taglib\list>notepad CartListTag.java.

3. Remove the following lines from CartListTag.java:

   public void setNumItems(String numItemsStr) {
   

   super.setNumItems(numItemsStr);
   

   }
   

     public void setStartIndex(String startIndexStr) {
   

   super.setNumItems(startIndexStr);
   

   }
   

4. Replace with the following:

   public void setNumItems(int numItems) {
   

   super.setNumItems(numItems);
   

   }
   

   public void setStartIndex(int startIndex) {
   

   super.setNumItems(startIndex);
   

   }
   

5. Save and close CartListTag.java.
6. Repeat steps 1 through 5 for the remaining files:

   MyListTag.java
   

   ProductItemListTag.java
   

   ProductListTag.java
   

   SearchListTag.java
   

 

Rebuild Petstore

After making the corrections to Pet Store, rebuild the application.

1. In a command console, change to the WebLogic Server 6.x WL_HOME\config\examples directory, and set your environment:

   WL_HOME\config\examples> setexamplesenv.cmd (or .sh)

2. In the same console, change to the WL_HOME\samples\petStore\src\petstore\src directory and rebuild:

   WL_HOME\samples\petStore\src\petstore\src> build

   The application builds petstore.ear to WL_HOME\samples\petStore\src\petstore\build.

3. Copy the new petstore.ear from WL_HOME\samples\petStore\src\petstore\build to WL_HOME\config\petstore\applications.

 

Upgrade the Pet Store Domain

In this upgrade procedure your WebLogic Server 8.1 configuration continues to point to the Cloudscape database used in WebLogic Server 6.1.

1. Create a new directory, 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.

2. Copy these two directories and their contents from the WebLogic Server 6.1 WL_HOME directory to C:\petstorefrom61to81:

   WL_HOME\config

   WL_HOME\samples

3. Open the config.xml file in C:\petstorefrom61to81\config\petstore in a text editor. For example:

   C:\petstorefrom61to81\config\petstore>notepad config.xml

4. Make the following edits to config.xml.
   1. Edit the application paths for petstore.ear and petstoreadmin.ear to point to C:\petstorefrom61to81. Replace:

      Path="WL_HOME\config\petstore\applications">

      with:

      Path="c:\petstorefrom61to81\config\petstore\applications">

   2. For the server's RootDirectory setting, replace the WebLogic Server 6.x WL_HOME path with the c:\petstorefrom61to81 path. That is, replace:

      Name="petstoreServer" RootDirectory="WL_HOME"

      with

      Name="petstoreServer" RootDirectory="C:\petstore61to81"

   3. Change the path from the WebLogic Server 6.x Java compiler to the WebLogic Server 8.1 Java compiler. For example, change the following setting (in which WL_HOME is the WebLogic Server 6.1 install directory)

      JavaCompiler="WL_HOME\jdk131\bin\javac"

      to the following (in which WL_HOME is the WebLogic Server 8.1 install directory):

      JavaCompiler="WL_HOME\jdk141_03\bin\javac"

5. Open the startpetstore.cmd (or .sh) script in C:\petstorefrom61to81\config\petstore. For example:

   C:\petstorefrom61to81\config\petstore>notepad startpetstore.cmd

6. Make the following edits to startpetstore.cmd or .sh:
   1. Change %JAVA_HOME% from the JDK your WebLogic Server 6.x installation uses to the JDK your WebLogic Server 8.1 installation uses. For example:

      set JAVA_HOME=WL_HOME\jdk131

      where WL_HOME is the WebLogic Server 6.1 installation directory, becomes:

      set JAVA_HOME=WL_HOME\jdk141

      where WL_HOME is the WebLogic Server 8.1 installation directory.

   2. Edit the line that checks which directory contains the script from:

      if not exist lib\weblogic.jar goto wrongplace

      to read:

      if not exist WL_HOME\server\lib\weblogic.jar goto wrongplace

      where WL_HOME is the WebLogic Server 8.1 installation directory.

   3. Change the classpath from

      set CLASSPATH=.;C:\bea\81feb26\weblogic81\server\lib\weblogic.jar;.WL_HOME61\samples\eval\cloudscape\lib\cloudscape.jar;.\config\petStore\serverclasses

      to

      set CLASSPATH=.;WL_HOME81\server\lib\weblogic.jar;.C:\petstorefrom61to81\samples\eval\cloudscape\lib\cloudscape.jar;C:\petstorefrom61to81\config\petstore\serverclasses

   4. Change the -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

      -Dbea.home=C:\bea\bea61

      to

      -Dbea.home=C:\bea\bea81

   5. Change the security policy setting, -Djava.security.policy, from the 6.x security policy file to the 8.1 security policy file. In the setting below, WL_HOME is the 6.x installation directory, and needs to be changed to point to the 8.1 installation directory.

      -Djava.security.policy=="WL_HOME/server/lib/weblogic.policy"

7. Test the upgrade by starting Pet Store using the C:\petstorefrom61to81\config\petstore\startpetstore.cmd or .sh command, and then browsing to http://localhost:7001/petstore to run the application.

 

---

Upgrading WebLogic Server 6.x Security to Version 8.1

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:

• Security Realms in WebLogic Server 8.1 Versus 6.x
• Upgrading Your WebLogic Server 6.x Security Realms to 8.1
• Access Control Lists (ACLs)
• Upgrading from Compatibility Security to WebLogic Server 8.1 Security
• Guest and <Anonymous> Users
• password.ini File
• Upgrading SSL

 

Security Realms in WebLogic Server 8.1 Versus 6.x

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.

 

Upgrading Your WebLogic Server 6.x Security Realms to 8.1

You have the following choices when upgrading a WebLogic Server 6.x security realm to WebLogic Server 8.1:

• Use Compatibility security - Booting WebLogic Server 8.1 in Compatibility security provides easy access to your WebLogic Server 6.x security configuration, including your users, groups, and ACLs. When using Compatibility security, however, the only security realm available is the 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.

• Use the Realm Adapter security providers - Configuring the Realm Adapter Authentication provider in a pure WebLogic Server 8.1 security realm (that is, a security realm other than the 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.

• Upgrading from an LDAP V2 Security Realm
• Upgrading from a Windows NT Security Realm
• Upgrading from a UNIX Security Realm
• Upgrading from an RDBMS Security Realm
• Upgrading from a Custom Security Realm

 

Upgrading from an LDAP V2 Security Realm

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 Verifying the Upgrade of ACLs to Security Roles and Security Policies and Securing WebLogic Resources.

To upgrade from a WebLogic Server 6.x LDAP V2 security realm to a WebLogic Server 8.1 security realm:

• Step 1: Verify and Capture Your WebLogic Server 6.x LDAP V2 Security Realm Configuration
• Step 2: Configure a WebLogic LDAP Authentication Provider
• Step 3: Enable Communication Between Your LDAP Server and WebLogic Server 8.1
• Step 4: Specify How Users and Groups are Stored in the LDAP Directory
• Step 5: Restart the WebLogic Server 8.1 Instance and Verify the Referenced Users and Groups

 

Step 1: Verify and Capture Your WebLogic Server 6.x LDAP V2 Security Realm Configuration

1. In the left pane of the WebLogic Server 6.x Administration Console, expand Security.
2. Click Users.

   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.

3. In the left pane of the WebLogic Server 6.x Administration Console, click Groups.

   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.

4. In the left pane of the WebLogic Server 6.x Administration Console, expand Realms.

   The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the LDAP V2 security realm.

5. Click the name of the LDAP V2 security realm.

   For example, click defaultLDAPRealmForNetscapeDirectoryServer.

6. On the Configuration tab:
   1. Select the contents of the Configuration Data field.

      For example, select:

      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

   2. Copy the selected text to a temporary location, such as a Notepad file.
7. Be sure you know the password for the user that can log into your LDAP server.
8. Check whether you have SSL enabled by navigating to the Servers - > myserver - > Configuration - > SSL tab in the WebLogic Server 6.x Administration Console, where myserver is the name of your WebLogic Server 6.x instance.
9. Record the values of any Cache Size and Cache TTL fields in the LDAP V2 security realm's associated Caching realm by navigating to the subtabs of Security - > Caching Realms - > myCachingRealm - > Configuration, where myCachingRealm is the name of your Caching realm.

 

Step 2: Configure a WebLogic LDAP Authentication Provider

1. In the left pane of the WebLogic Server 8.1 Administration Console, expand myrealm - > Providers - > Authentication.

   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.

2. Click on the Authentication node.
3. In the right pane of the WebLogic Server 8.1 Administration Console, click the Configure a New... link that corresponds to the type of LDAP server you have.

   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.

4. On the General tab, provide a name for the LDAP Authentication provider.
5. Select a value for the Control Flag field.

   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.

6. Click Create.

   The LDAP Authentication provider you configured appears in the list under the Authentication node in the left pane of the WebLogic Server 8.1 Administration Console.

 

Step 3: Enable Communication Between Your LDAP Server and WebLogic Server 8.1

1. On the <LDAPServerName> LDAP tab of the WebLogic Server 8.1 Administration Console, use the information you saved in step 6 of Step 1: Verify and Capture Your WebLogic Server 6.x LDAP V2 Security Realm Configuration to fill in the following fields:
   1. Host - the value of server.host
   2. Port - the value of server.port
   3. Principal - the value of server.principal (after the first = sign)
   4. In the Credential/Confirm Credential fields, enter the password for the user that can log into your LDAP server.
2. If your WebLogic Server 6.x instance had SSL enabled, check the SSL Enabled field so there is a checkmark in the box.
3. Accept the default values for the Cache Enabled, Cache Size, and Cache TTL fields.

   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.

4. Click Apply.

Warning: Do not yet restart the WebLogic Server 8.1 instance called myserver, even if the restart icon is flashing.

 

Step 4: Specify How Users and Groups are Stored in the LDAP Directory

1. On the Users tab of the WebLogic Server 8.1 Administration Console, use the information you saved in step 6 of Step 1: Verify and Capture Your WebLogic Server 6.x LDAP V2 Security Realm Configuration to fill in the following fields:

   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.

2. Click Apply.
3. On the Groups tab, use the information you saved in step 6 of Step 1: Verify and Capture Your WebLogic Server 6.x LDAP V2 Security Realm Configuration to fill in the following fields:

   Group Base DN - the value of group.dn

   Group From Name Filter - the value of group.filter (the default in the WebLogic Server 8.1 Administration Console may already be correct)

   Note: Accept the defaults for other fields on the Groups tab or fill in appropriate information.

4. Click Apply.

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.

 

Step 5: Restart the WebLogic Server 8.1 Instance and Verify the Referenced Users and Groups

1. Save a copy of the WebLogic Server 8.1 config.xml.booted file.

   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.

2. Stop the WebLogic Server 8.1 instance called myserver by following these steps:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Servers.

      The Servers node expands to show the WebLogic Server 8.1 instances that have already been configured in the mydomain WebLogic Server 8.1 domain.

   2. Right-click myserver, and select the Start/Stop This Server... option from the menu.
   3. On the Start/Stop tab, click the Graceful Shutdown of This Server... link.
   4. Click Yes.
3. Restart the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
4. Log back into the WebLogic Server 8.1 Administration Console.
5. In the left pane of the WebLogic Server 8.1 Administration Console, expand Security - > Realms - > myrealm.
6. Click Users.

   A table that lists all the users for the myrealm security realm appears in the right pane. This table includes the users from your WebLogic Server 6.x LDAP V2 security realm.

7. In the left pane of the WebLogic Server 8.1 Administration Console, click Groups.

   A table that lists all the groups for the myrealm security realm appears in the right pane. This table includes the groups from your WebLogic Server 6.x LDAP V2 security realm.

 

Upgrading from a Windows NT Security Realm

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 Verifying the Upgrade of ACLs to Security Roles and Security Policies and Securing WebLogic Resources.

To upgrade from a WebLogic Server 6.x Windows NT security realm to a WebLogic Server 8.1 security realm:

• Step 1: Verify and Capture Your WebLogic Server 6.x Windows NT Security Realm Configuration
• Step 2: Configure a Realm Adapter Authentication Provider
• Step 3: Reconfigure Your WebLogic Server 6.x Windows NT Realm in WebLogic Server 8.1 Compatibility Security
• Step 4: Restart the WebLogic Server 8.1 Instance and Verify the Referenced Users and Groups

 

Step 1: Verify and Capture Your WebLogic Server 6.x Windows NT Security Realm Configuration

1. In the left pane of the WebLogic Server 6.x Administration Console, expand Security.
2. Click Users.

   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.

3. In the left pane of the WebLogic Server 6.x Administration Console, click Groups.

   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.

4. In the left pane of the WebLogic Server 6.x Administration Console, expand Realms.

   The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the Windows NT security realm.

5. Click the name of the Windows NT security realm.

   For example, click MyNTRealm.

6. On the Configuration tab, copy the contents of the Primary Domain field to a temporary location, such as a Notepad file.
7. Be sure you know the password for the user that can log into your Windows NT server.
8. Check whether you have SSL enabled by navigating to the Servers - > myserver - > Configuration - > SSL tab in the WebLogic Server 6.x Administration Console, where myserver is the name of your WebLogic Server 6.x instance.
9. Record the values of any Cache Size and Cache TTL fields in the Windows NT security realm's associated Caching realm by navigating to the subtabs of Security - > Caching Realms - > myCachingRealm - > Configuration, where myCachingRealm is the name of your Caching realm.

 

Step 2: Configure a Realm Adapter Authentication Provider

Note: For a detailed explanation of the Realm Adapter Authentication provider, see Configuring a Realm Adapter Authentication Provider" in Managing WebLogic Security.

1. In the left pane of the WebLogic Server 8.1 Administration Console, expand myrealm - > Providers - > Authentication.

   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.

2. Click on the Authentication node.
3. In the right pane of the WebLogic Server 8.1 Administration Console, click the Configure a New Realm Adapter Authenticator... link.
4. On the General tab, provide a name for the Realm Adapter Authentication provider.
5. If it is not already selected, set the Control Flag field to OPTIONAL.

   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.

6. Click Create.

   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.

   The Realm Adapter Authentication provider you configured appears in the list under the Authentication node in the left pane of the WebLogic Server 8.1 Administration Console.

 

Step 3: Reconfigure Your WebLogic Server 6.x Windows NT Realm in WebLogic Server 8.1 Compatibility Security

1. Save a copy of the WebLogic Server 8.1 config.xml.booted file.

   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.

2. Stop the WebLogic Server 8.1 instance called myserver by following these steps:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Servers.

      The Servers node expands to show the WebLogic Server 8.1 instances that have already been configured in the mydomain WebLogic Server 8.1 domain.

   2. Right-click myserver, and select the Start/Stop This Server... option from the menu.
   3. On the Start/Stop tab, click the Graceful Shutdown of This Server... link.
   4. Click Yes.
3. Restart the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
4. Log back into the WebLogic Server 8.1 Administration Console.

   The Compatibility Security node appears in the left pane of the WebLogic Server 8.1 Administration Console.

5. In the left pane of the WebLogic Server 8.1 Administration Console, expand Compatibility Security.
6. Click Realms.
7. In the right pane of the WebLogic Server 8.1 Administration Console, click the Configure a New NT Realm (Deprecated)... link.

   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.

8. On the General tab, use the information you saved in step 6 of Step 1: Verify and Capture Your WebLogic Server 6.x Windows NT Security Realm Configuration to:
   • Provide a name for the Windows NT realm.
   • Provide the primary domain of your original, 6.x Windows NT realm.

     Note: If entering multiple sets of host numbers, delimit them with commas. If the local computer (where WebLogic Server executes) is the Primary Controller, you can just enter a period (".").

9. Click Create.
10. In the left pane of the WebLogic Server 8.1 Administration Console, click Caching Realms.
11. In the right pane of the WebLogic Server 8.1 Administration Console, select the Configure a New Caching Realm... link.
12. On the General tab:
    • Provide a name for the Caching realm.
    • Select the name of the Windows NT realm as the Basic Realm.
    • Click Create.
13. In the left pane of the WebLogic Server 8.1 Administration Console, click Compatibility Security.
14. Select the Compatibility tab.
15. On the File Realm tab:
    • Select the name of the Caching realm you created in step 12 from the Caching Realm drop-down menu.
    • Click Apply.

 

Step 4: Restart the WebLogic Server 8.1 Instance and Verify the Referenced Users and Groups

1. Save a copy of the WebLogic Server 8.1 config.xml.booted file.

   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.

2. Stop the WebLogic Server 8.1 instance called myserver by following these steps:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Servers.

      The Servers node expands to show the WebLogic Server 8.1 instances that have already been configured in the mydomain WebLogic Server 8.1 domain.

   2. Right-click myserver, and select the Start/Stop This Server... option from the menu.
   3. On the Start/Stop tab, click the Graceful Shutdown of This Server... link.
   4. Click Yes.
3. Restart the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
4. Log back into the WebLogic Server 8.1 Administration Console.
5. In the left pane of the WebLogic Server 8.1 Administration Console, expand Compatibility Security.
6. Click Users.

   The users from your WebLogic Server 6.x Windows NT security realm appear at the bottom of the right pane.

7. In the left pane of the WebLogic Server 8.1 Administration Console, click Groups.

   A table that lists all the groups for the CompatibilityRealm security realm appears in the right pane. This table includes the groups from your WebLogic Server 6.x Windows NT security realm.

 

Upgrading from a UNIX Security Realm

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 Verifying the Upgrade of ACLs to Security Roles and Security Policiesand Securing WebLogic Resources.

To upgrade from a WebLogic Server 6.x Unix security realm to a WebLogic Server 8.1 security realm:

• Step 1: Verify and Capture Your WebLogic Server 6.x Unix Security Realm Configuration
• Step 2: Configure a Realm Adapter Authentication Provider
• Step 3: Reconfigure Your WebLogic Server 6.x Unix Realm in WebLogic Server 8.1 Compatibility Security
• Step 4: Restart the WebLogic Server 8.1 Instance and Verify the Referenced Users and Groups

 

Step 1: Verify and Capture Your WebLogic Server 6.x Unix Security Realm Configuration

1. In the left pane of the WebLogic Server 6.x Administration Console, expand Security.
2. Click Users.

   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.

3. In the left pane of the WebLogic Server 6.x Administration Console, click Groups.

   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.

4. In the left pane of the WebLogic Server 6.x Administration Console, expand Realms.

   The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the Unix security realm.

5. Click the name of the Unix security realm.

   For example, click MyUnixRealm.

6. On the Configuration tab, copy the contents of the Auth Program field to a temporary location, such as a Notepad file.
7. Be sure you know the password for the user that can log into your Unix server.
8. Check whether you have SSL enabled by navigating to the Servers - > myserver - > Configuration - > SSL tab in the WebLogic Server 6.x Administration Console, where myserver is the name of your WebLogic Server 6.x instance.
9. Record the values of any Cache Size and Cache TTL fields in the Unix security realm's associated Caching realm by navigating to the subtabs of Security - > Caching Realms - > myCachingRealm - > Configuration, where myCachingRealm is the name of your Caching realm.

 

Step 2: Configure a Realm Adapter Authentication Provider

Note: For a detailed explanation of the Realm Adapter Authentication provider, see Configuring a Realm Adapter Authentication Provider" in Managing WebLogic Security.

1. In the left pane of the WebLogic Server 8.1 Administration Console, expand myrealm - > Providers - > Authentication.

   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.

2. Click on the Authentication node.
3. In the right pane of the WebLogic Server 8.1 Administration Console, click the Configure a New Realm Adapter Authenticator... link.
4. On the General tab, provide a name for the Realm Adapter Authentication provider.
5. If it is not already selected, set the Control Flag field to OPTIONAL.

   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.

6. Click Create.

   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.

   The Realm Adapter Authentication provider you configured appears in the list under the Authentication node in the left pane of the WebLogic Server 8.1 Administration Console.

 

Step 3: Reconfigure Your WebLogic Server 6.x Unix Realm in WebLogic Server 8.1 Compatibility Security

1. Save a copy of the WebLogic Server 8.1 config.xml.booted file.

   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.

2. Stop the WebLogic Server 8.1 instance called myserver by following these steps:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Servers.

      The Servers node expands to show the WebLogic Server 8.1 instances that have already been configured in the mydomain WebLogic Server 8.1 domain.

   2. Right-click myserver, and select the Start/Stop This Server... option from the menu.
   3. On the Start/Stop tab, click the Graceful Shutdown of This Server... link.
   4. Click Yes.
3. Restart the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
4. Log back into the WebLogic Server 8.1 Administration Console.

   The Compatibility Security node appears in the left pane of the WebLogic Server 8.1 Administration Console.

5. In the left pane of the WebLogic Server 8.1 Administration Console, expand Compatibility Security.
6. Click Realms.
7. In the right pane of the WebLogic Server 8.1 Administration Console, click the Configure a New Unix Realm (Deprecated)... link.

   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.

8. On the Configuration tab, use the information you saved in step 6 of Step 1: Verify and Capture Your WebLogic Server 6.x Windows NT Security Realm Configuration to:
   • Provide a name for the Unix realm.
   • Provide the name of the authentication program used in your original, 6.x Unix realm.

     Note: wlauth is the name of a small native program provided by default as part of WebLogic Server. wlauth is executed to look up users and groups and to authenticate users on the basis of their Unix login names and passwords.

9. Click Create.
10. In the left pane of the WebLogic Server 8.1 Administration Console, click Caching Realms.
11. In the right pane of the WebLogic Server 8.1 Administration Console, select the Configure a New Caching Realm... link.
12. On the General tab:
    • Provide a name for the Caching realm.
    • Select the name of the Unix realm as the Basic Realm.
    • Click Create.
13. In the left pane of the WebLogic Server 8.1 Administration Console, click Compatibility Security.
14. Select the Compatibility tab.
15. On the File Realm tab:
    • Select the name of the Caching realm you created in step 12 from the Caching Realm drop-down menu.
    • Click Apply.

 

Step 4: Restart the WebLogic 8.1 Server Instance and Verify the Referenced Users and Groups

1. Save a copy of the WebLogic Server 8.1 config.xml.booted file.

   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.

2. Stop the WebLogic Server 8.1 instance called myserver by following these steps:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Servers.

      The Servers node expands to show the WebLogic Server 8.1 instances that have already been configured in the mydomain WebLogic Server 8.1 domain.

   2. Right-click myserver, and select the Start/Stop This Server... option from the menu.
   3. On the Start/Stop tab, click the Graceful Shutdown of This Server... link.
   4. Click Yes.
3. Restart the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
4. Log back into the WebLogic Server 8.1 Administration Console.
5. In the left pane of the WebLogic Server 8.1 Administration Console, expand Compatibility Security.
6. Click Users.

   The users from your WebLogic Server 6.x Unix security realm appear at the bottom of the right pane.

7. In the left pane of the WebLogic Server 8.1 Administration Console, click Groups.

   A table that lists all the groups for the CompatibilityRealm security realm appears in the right pane. This table includes the groups from your WebLogic Server 6.x Unix security realm.

 

Upgrading from an RDBMS Security Realm

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 Verifying the Upgrade of ACLs to Security Roles and Security Policiesand Securing WebLogic Resources.

To upgrade from a WebLogic Server 6.x RDBMS security realm to a WebLogic Server 8.1 security realm:

• Step 1: Verify and Capture Your WebLogic Server 6.x RDBMS Security Realm Configuration
• Step 2: Recompile the WebLogic Server 6.x RDBMS Realm Code for Use in WebLogic Server 8.1
• Step 3: Configure a Realm Adapter Authentication Provider
• Step 4: Modify the WebLogic Server 8.1 Start Script
• Step 5: Reconfigure Your WebLogic Server 6.x RDBMS Realm in WebLogic Server 8.1 Compatibility Security
• Step 6: Restart the WebLogic Server 8.1 Instance and Verify the Referenced Users and Groups

 

Step 1: Verify and Capture Your WebLogic Server 6.x RDBMS Security Realm Configuration

1. In the left pane of the WebLogic Server 6.x Administration Console, expand Security.
2. Click Users.

   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.

3. In the left pane of the WebLogic Server 6.x Administration Console, click Groups.

   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.

4. In the left pane of the WebLogic Server 6.x Administration Console, expand Realms.

   The Realms node expands to show the security realms for the WebLogic Server 6.x domain, including the RDBMS security realms.

5. Click the name of an RDBMS security realm.

   For example, click DefaultRDBMSRealmForCloudscape.

6. On the Configuration tab, copy the following information to a temporary location, such as a Notepad file:
   1. On the General tab, the contents of the Name and Realm Class fields. Note that the out-of-the-box RDBMS example used examples.security.rdbmsrealm.RDBMSRealm as the value for the Realm Class.
   2. On the Database tab, the contents of the Driver, URL, and User Name and Password fields, if applicable. Note that 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.
   3. On the Schema tab, the contents of the Schema Properties field.

      For example:

      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 = ?

 

Step 2: Recompile the WebLogic Server 6.x RDBMS Realm Code for Use in WebLogic Server 8.1

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:

1. Modify the 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.
2. Save the RDBMSDelegate.java file.
3. Run the setenv script provided with WebLogic Server 8.1.
4. Recompile all the RDBMS realm sample code directly from the 6.x WL_HOME\samples\examples\ directory, using javac.

 

Step 3: Configure a Realm Adapter Authentication Provider

Note: For a detailed explanation of the Realm Adapter Authentication provider, see Configuring a Realm Adapter Authentication Provider" in Managing WebLogic Security.

1. In the left pane of the WebLogic Server 8.1 Administration Console, expand myrealm - > Providers - > Authentication.

   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.

2. Click on the Authentication node.
3. In the right pane of the WebLogic Server 8.1 Administration Console, select the Configure a New Realm Adapter Authenticator... link.
4. On the General tab, provide a name for the Realm Adapter Authentication provider.
5. If it is not already selected, set the Control Flag field to OPTIONAL.

   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.

6. Click Create.

   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.

   The Realm Adapter Authentication provider you configured appears in the list under the Authentication node in the left pane of the WebLogic Server 8.1 Administration Console.

 

Step 4: Modify the WebLogic Server 8.1 Start Script

1. Stop the WebLogic Server 8.1 instance called myserver by following these steps:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Servers.

      The Servers node expands to show the WebLogic Server 8.1 instances that have already been configured in the mydomain WebLogic Server 8.1 domain.

   2. Right-click myserver, and select the Start/Stop This Server... option from the menu.
   3. On the Start/Stop tab, click the Graceful Shutdown of This Server... link.
   4. Click Yes.
2. Open the StartWebLogic.cmd/sh file in a text editor and update the CLASSPATH to include paths to:
   • The 6.x RDBMS realm code you re-compiled in Step 2: Recompile the WebLogic Server 6.x RDBMS Realm Code for Use in WebLogic Server 8.1.
   • The WebLogic Server 6.x cloudscape.jar file, which is installed under WL_HOME\samples\eval\cloudscape\lib.
3. Save the modified StartWebLogic.cmd/sh file.

 

Step 5: Reconfigure Your WebLogic Server 6.x RDBMS Realm in WebLogic Server 8.1 Compatibility Security

1. Save a copy of the WebLogic Server 8.1 config.xml.booted file.

   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.

2. Stop the WebLogic Server 8.1 instance called myserver by following these steps:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Servers.

      The Servers node expands to show the WebLogic Server 8.1 instances that have already been configured in the mydomain WebLogic Server 8.1 domain.

   2. Right-click myserver, and select the Start/Stop This Server... option from the menu.
   3. On the Start/Stop tab, click the Graceful Shutdown of This Server... link.
   4. Click Yes.
3. Restart the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
4. Log back into the WebLogic Server 8.1 Administration Console.

   The Compatibility Security node appears in the left pane of the WebLogic Server 8.1 Administration Console.

5. In the left pane of the WebLogic Server 8.1 Administration Console, expand Compatibility Security.
6. Click Realms.
7. In the right pane of the WebLogic Server 8.1 Administration Console, select the Configure a New RDBMS Realm (Deprecated)... link.

   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.

8. On the Configuration tab:
   • Provide a name for the RDBMS realm.
   • Click Create.
9. In the left pane of the WebLogic Server 8.1 Administration Console, click Caching Realms.
10. In the right pane of the WebLogic Server 8.1 Administration Console, select the Configure a New Caching Realm... link.
11. On the General tab:
    • Provide a name for the Caching realm.
    • Select the name of the RDBMS realm as the Basic Realm.
    • Click Create.
12. In the left pane of the WebLogic Server 8.1 Administration Console, click Compatibility Security.
13. Select the Compatibility tab.
14. On the File Realm tab:
    • Select the name of the Caching realm you created in step 11 from the Caching Realm drop-down menu.
    • Click Apply.

 

Step 6: Restart the WebLogic Server 8.1 Instance and Verify the Referenced Users and Groups

1. Restart the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
2. Log into the WebLogic Server 8.1 Administration Console.
3. In the left pane of the WebLogic Server 8.1 Administration Console, expand Compatibility Security.
4. Click Users.

   The users from your WebLogic Server 6.x RDBMS security realm appear at the bottom of the right pane.

5. In the left pane of the WebLogic Server 8.1 Administration Console, click Groups.

   A table that lists all the groups for the CompatibilityRealm security realm appears in the right pane. This table includes the groups from your WebLogic Server 6.x RDBMS security realm.

 

Upgrading from a Custom Security Realm

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:

• You Have a 5.x weblogic.properties File Instead of a 6.x config.xml File
• You Upgraded a WebLogic Server 6.x Domain "In Place"

 

You Have a 5.x weblogic.properties File Instead of a 6.x config.xml File

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:

• Implement the BasicRealm.getUser(String)or BasicRealm.getUser(UserInfo) method in your CustomRealm class. This method should return null for system, everyone and Administrators.
• Implement the 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.

 

You Upgraded a WebLogic Server 6.x Domain "In Place"

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:

• The recomplilation of the 6.x realm code against WebLogic Server 8.1.
• Use of the new MBean API described in MBean API Change.

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.

 

Access Control Lists (ACLs)

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
• ACLs That Protected WebLogic Resources
• Verifying the Upgrade of ACLs to Security Roles and Security Policies

 

ACLs on MBeans

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.

 

ACLs That Protected 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 Verifying the Upgrade of ACLs to Security Roles and Security Policies and Default Security Policies" in Securing WebLogic Resources for more information.

 

Verifying the Upgrade of ACLs to Security Roles and Security Policies

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.

1. If it is not already running, start the WebLogic Server 8.1 instance called myserver by selecting Programs - > BEA WebLogic Platform 8.1 - > User Projects - > domains - > mydomain - > Start Server.
2. Log into the WebLogic Server 8.1 Administration Console.
3. In the left pane of the WebLogic Server 8.1 Administration Console, expand Compatibility Security - > ACLs.

   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.

4. Verify the upgrade of ACLs by:
   1. Right-clicking a WebLogic resource in the left pane of the WebLogic Server 8.1 Administration Console. For example, right-click Servers.

      For more information about WebLogic resources, see Types of WebLogic Resources" in Securing WebLogic Resources.

   2. Select the Define Security Policy... option.
   3. In the Policy Statement list box of the displayed Policy Editor page, you see the upgraded security policy for the WebLogic resource.

      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.

   4. Repeat steps a - c for each ACL you want to verify. Note that 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 and Listing 4.

Listing 3 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 4 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

 

Upgrading from Compatibility Security to WebLogic Server 8.1 Security

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:

1. In the WebLogic Server 8.1 Administration Console, click the Realms node.

   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.

2. Click the myrealm node.
3. Select the Providers tab to see the security providers configured for myrealm. By default, the WebLogic security providers are configured in myrealm.
4. Add a user that can boot the WebLogic Server 8.1 instance to the Administrators group. This user replaces the system user. To add a user to the Administrators group:
   1. In the left pane of the WebLogic Server 8.1 Administration Console, expand Security - > Realms.
   2. Expand the name of the realm you are configuring (for example, myrealm).
   3. Click Groups.
   4. The Groups tab appears. This tab displays the names of all groups defined in the WebLogic Authentication provider.
   5. Click the Administrators link on the Groups tab.
   6. Select the Membership tab and add the user who can boot WebLogic Server to the Administrators group.
   7. Click Apply.
5. Make sure the users and groups you had configured in the 6.x security realm have been added to an Authentication provider. For more information, see Upgrading Your WebLogic Server 6.x Security Realms to 8.1.
6. Optionally, define security roles for your WebLogic Server 6.x users and groups. For more information, see Security Roles" in Securing WebLogic Resources.
7. Express any ACLs you added in WebLogic Server 6.x as security policies. For more information, see Working with Security Policies" in Securing WebLogic Resources.
8. Set 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.
9. Reboot the WebLogic Server 8.1 instance.

   Each time the WebLogic Server 8.1 instance is booted, the security roles and security policies are applied. Subsequent access to the server and its methods are constrained by these security roles and security policies until they are changed.

 

Guest and <Anonymous> Users

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:

• Use Compatibility security. (For more information, see Using Compatibility Security" in Managing WebLogic Security.)
• Define the 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:

  -Dweblogic.security.anonymousUserName=guest

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.

 

password.ini File

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.

 

Upgrading SSL

This section contains the following information about upgrading SSL:

• Upgrading SSL Identity and Trust
• New Options for Storing SSL Client Trust
• Using Host Name Verification
• Using a Certificate Authenticator

 

Upgrading SSL Identity and Trust

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. 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.

 

New Options for Storing SSL Client Trust

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:

• Demo Trust - The trusted CA certificates in the demonstration Trust keystore (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.

• Custom Trust - A trust keystore you create. To use Custom Trust, specify the following command-line arguments:

  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.

 

Using Host Name Verification

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.

 

Using a Certificate Authenticator

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:

1. Expand the Security - > Realms nodes.
2. Select CompatibilityRealm.
3. Expand the Providers node.
4. Select Authentication Providers.
5. Click the Realm Adapter Authenticator link in the Realms table.
6. On the General tab, enter X.509 in the Active Types list box.

   Note: This step enables the use of 6.x Cert Authenticators.

7. Click Apply.
8. Reboot the WebLogic Server 8.1 instance.

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.

 

---

Additional Upgrade Procedures and Information

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.

• Apache Xalan XML Transformer
• Apache Xerces XML Parser
• Deployment
• Manual Changes to Deployment Descriptors for EJB 2.0
• jCOM
• Upgrading Your JDK
• JMS
• JMX
• Jolt Java Client
• Upgrading Your JVM to JRockit" on page 57
• JSP
• 6.1 Managed Servers Cannot Boot from an 8.1 Administrative Server
• MBean API Change
• Default Queue Names Have Changed
• ThreadPoolSize Is Now ThreadCount
• Web Application API Changes from 6.0
• Clusters on Solaris Perform Better with Client JVM
• Change WebLogic Tuxedo Connector Configuration
• Upgrade Web Services
• Deprecated APIs and Features
• Removed APIs and Features

 

Apache Xalan XML Transformer

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.

 

Apache Xerces XML Parser

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.

 

Runtime Modes

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.

 

Deployment

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, 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.

 

Manual Changes to Deployment Descriptors for EJB 2.0

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:

• If your deployment descriptor contains a 6.0 element that has a different name in 8.1, you have to manually change the name in your deployment descriptor. The following are some examples of element names that you may need to change in 8.1:
  • In 8.1, the name of the element that is used to identify a particular EJB that participates in a relationship is relationship-role-source. In 6.0, the element name was role-source.
  • In 8.1, the name of the element that specifies whether the destination is a queue or a topic is destination-type. In 6.0, the element name was jms-destination-type.
  • In 8.1, the name of the element that specifies whether the destination is a queue or a topic is run-as. In 6.0, the element name was run-as-specified-identity.
• In 8.1, EJB-QL queries require a SELECT clause.
• All EJB 2.0 CMP beans must have an 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:

• There were no local interfaces in 6.0, but they exist in 6.1 and 7.0 and 8.1.
• Remote relationships do not exist in 6.0, but do exist in 6.1 and 7.0 and 8.1.
• The new implementation of read-only beans in WebLogic Server 7.0 and after does not require 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.
• In pre-2.0 final versions of the WebLogic Server EJB implementation you could refer to a CMP or CMR field in a EJB QL query without using a qualified path. However, as of the final specification, all EJB QL queries must have a qualified path.
• The implementation of read-only beans in version 7.0 does not require 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.

 

weblogic.management.configuration.EJBComponentMBean Changes

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.

 

max-beans-in-cache Parameter

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.

 

Fully Qualified Path Expressions

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:

• WebLogic Server 6.x would allow the following query to compile:

  SELECT address FROM CustomerBean AS c WHERE zip = ?1 
  

• For WebLogic Server 8.1 to allow the same query to be compiled, the address and zip fields must be qualified:

  SELECT c.address FROM CustomerBean AS c WHERE c.zip = ?1
  

 

jCOM

For information about upgrading from WebLogic jCOM 6.1 to WebLogic jCOM 8.1 see Upgrading Considerations in Programming WebLogic jCOM.

 

JDBC

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.

 

Upgrading Your JDK

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.

 

Stricter JSP Parsing in JDK 1.3.1_09

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. */

 

WebLogic Server 8.1 Dependencies on JDK 1.4

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.

 

JMS

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.

 

JMX

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 Java Client

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.

 

Upgrading Your JVM to JRockit

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:

• It employs adaptive optimization, which detects and removes bottlenecks in the deployed application.
• It is designed specifically for the special requirements of server-side applications, which tend to be parallel and thread-intensive, to run for longer periods of time, and not to use graphical interfaces.
• You can monitor JRockit using the WebLogic Server Administration Console.

To switch a WebLogic Server domain to the JRockit JVM:

1. In the server start scripts, set 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.

2. Change the domain's config.xml to use the JRockit javac.exe. For example, change

   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.

3. Remove from server start scripts any switches specific to the Sun JVM. For example, from the start command:

   echo on "%JAVA_HOME%\bin\java" -hotspot .... weblogic.Server
   

   delete "-hotspot".

4. Start and configure JRockit. See Starting and Configuring the WebLogic JRockit JVM.

For JRockit platform and user information, see the JRockit User Guide at.

 

JSP

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 :

<weblogic-web-app>

<jsp-param>

<param-name>printNulls</param-name>

<param-value>false</param-value>

</jsp-param>

</weblogic-web-app>

 

New Behavior of Load Order Methods for Startup Classes

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.

 

6.1 Managed Servers Cannot Boot from an 8.1 Administrative Server

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 Queue Names Have Changed

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.

 

Pre-8.1Default Queue Names		WebLogic Server 8.1 Default Queue Names
default		weblogic.kernel.Default
__weblogic_admin_html_queue		weblogic.admin.RMI
__weblogic_admin_rmi_queue		weblogic.admin.HTTP

 

MBean API Change

In previous versions, the weblogic.management.Admin class had the static method, getActiveDomain(). In Weblogic Server 8.1, getActiveDomain() is no longer static. In its place, use Admin.getInstance().getAdminMBeanHome().getActiveDomain();

For an example of how to use this new method, see Determining the Active Domain and Servers in Programming WebLogic Server JMX Services.

 

Update Your web.xml file with New Classes

For servlets, update your web.xml file so that it uses the following new classes:

weblogic.servlet.proxy.HttpClusterServlet

instead of

weblogic.servlet.internal.HttpClusterServlet

and

weblogic.servlet.proxy.HttpProxyServlet

instead of

weblogic.t3.srvr.HttpProxyServlet

If you have trouble with a servlet within the scope of application deployment see Deployment.

 

ThreadPoolSize Is Now ThreadCount

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:

1. In the console, select Servers > myServer > Monitoring > .
2. Click on Monitor all Active Queues.
3. Click on "default" queue (a list of threads and what they are doing appears).
4. Click on Configure Execute Queues (at the top of the page).
5. Click on "default" queue.
6. Enter the number of threads associated with this server.
7. Restart the server to make changes take effect.

 

404 Message for URIs with Extra Spaces

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.

 

Web Application API Changes from 6.0

• The 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().
• It is no longer possible to use the Administration Console to define the default Web application. Define the default Web application by setting the 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 "/".
• With Java Servlet Specification 2.3, authorization-on-forward is no longer default behavior. To obtain authorization when you forward to a secure resource, add <check-auth-on-forward> to the weblogic.xml file.
• Servlet Request and Response objects have a new API. Some serializable, lightweight implementations of these may no longer compile without implementing the new API. It is strongly recommended that you use the Servlet 2.3 model and substitute your implementations of Servlet Request and Response objects. If you did this in WebLogic Server 6.0, you were probably relying on the undocumented, internal implementations of these objects. WebLogic Server 8.1 supports Servlet 2.3, so you should be able to take advantage of the new ServletRequest/ResponseWrapper objects.

 

Clusters on Solaris Perform Better with Client JVM

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.

 

Change WebLogic Tuxedo Connector Configuration

You must make the following application and configuration changes to use WebLogic Tuxedo Connector in WebLogic Server 8.1:

• Start the WebLogic Tuxedo Connector
• Convert WebLogic Tuxedo Connector XML Configuration Files
• Update Inbound RMI-IIOP Applications
• Authenticate Remote Users
• Set WebLogic Tuxedo Connector Properties
• Using the Runtime WTC ORB

 

Start the WebLogic Tuxedo Connector

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.

• You start a WebLogic Tuxedo Connector session when you assign a WTC Service to a selected server.
• You end a WebLogic Tuxedo Connector session by removing a WTC Service from a selected server or when you shut down WebLogic Server.

For more information on starting and ending a WebLogic Tuxedo Connector session, see Assign a WTC Service to a Server.

 

Convert WebLogic Tuxedo Connector XML Configuration Files

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:

1. Set up a WebLogic Server development shell as described in Setting Up your environment.
2. Start an instance of WebLogic Server.
3. Open a new shell window.
4. Start the WTCMigrateCF tool. Enter the following command:

   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:

 

Argument	Description
-Dweblogic.wtc.migrateDebug	WebLogic property used to turn on wtc.migrateDebug mode.
URL	URL passed to your server. Example: \\myServer:7001
USERNAME	User Name passed to your server. Example: system
PASSWORD	Password passed to your server. Example: mypasswd
CONFIGWTC	Fully qualified path and name of the WebLogic Tuxedo Connector XML configuration file to migrate to the config.xml file. Example: d:\bea\weblogic81\server\samples\examples\wtc\atmi\simpapp\bdmconfig.xml
SERVERNAME	Optional. The name of the administration or managed server that you want the new WTCServer MBean assigned to. Default: the current active administration server.
DOMAIN	Optional. The name of the WebLogic Server 8.1 domain that you want the new WTCServer MBean assigned to. Default: the current active domain.
PROTOCOL	Optional. The protocol to use with URL. Default: t3:
-deploy	Optional. Use to target the WTCServer MBean to a selected server. If this flag is set, a WebLogic Tuxedo Connector session is immediately started to provide the services specified by the WTCServer MBean is immediately started.

When the migration is complete, the migration utility displays:

The WTC configuration file migration is done!

No error found!!!

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.

 

Update Inbound RMI-IIOP Applications

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, 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.

1. Modify the corbaloc:tgiop or corbaname:tgiop object reference in your ior.txt file.

   Example: corbaloc:tgiop:servername/NameService

   where servername is your server name

2. Register the WebLogic Server (WLS) Naming Service by entering the following command:

   cnsbind -o ior.txt your_bind_name

   where your_bind_name is the object name from your Tuxedo application.

3. Modify the *DM_REMOTE_SERVICES section of your Tuxedo domain configuration file. Replace your WebLogic Server service name, formerly the DOMAINID, with the name of your WebLogic Server.

Listing 1-1 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"

where servername is the name of your WebLogic Server where the WTC Service is running.

1. Load your modified domain configuration file using dmloadcf.

You are now ready to start your applications.

 

Authenticate Remote Users

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:

• LOCAL
• GLOBAL

 

ACL Policy is LOCAL

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:

1. Click on the Security node.
2. Click on Realms.
3. Select your default security Realm.
4. Click on Users.
5. Click the Configure a new User text link.
6. In the General tab, do the following:
   1. Add the Tuxedo DOMAINID in the Name field.
   2. Enter and validate a password.
   3. Click Apply.

 

ACL Policy is Global

If the WebLogic Tuxedo Connector ACL Policy is GLOBAL, the user's security token is passed. No administration changes are required.

 

Set WebLogic Tuxedo Connector Properties

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, set the tracing level using the WebLogic Server TraceLevel property. For more information, see Monitoring the WebLogic Tuxedo Connector .

• -Dweblogic.wtc.TraceLevel=tracelevel

  where tracelevel is a number between 10,000 and 100,000 that specifies the level of WebLogic Tuxedo Connector tracing.

To generate passwords using the weblogic.wtc.gwt.genpasswd utility, set a password key using the WebLogic Server PasswordKey property. For more information on how to generate passwords, see Configuring a WTCPassword MBean .

• -Dweblogic.wtc.PasswordKey=mykey

  where mykey is the key value.

 

Using the Runtime WTC ORB

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.

 

Upgrade Web Services

Due to changes in the Web service runtime system and architecture between versions 6.1 and 8.1 of WebLogic Server, 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.

 

Deprecated APIs and Features

• WebLogic Time Services is deprecated and should be replaced by JMX Timer Service. For documentation of JMX Timer Service, see Interface TimerMBean and Class Timer.
• WebLogic Workspaces
• Zero Administration Client (ZAC) is deprecated in this release of WebLogic Server 8.1. It is replaced by JavaWebStart.
• WebLogic Enterprise Connectivity (WLEC) is deprecated in this release of WebLogic Server 8.1. Tuxedo CORBA applications using WLEC should migrate to WebLogic Tuxedo Connector. For more information, see WebLogic Tuxedo Connector.
• 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.
• If you did programmatic deployment or used the 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.

 

Removed APIs and Features

WebLogic Enterprise Connectivity (WLEC) examples have been removed.