Skip navigation.
Downloads | Product Documentation | Support

WebLogic Server 8.1 Upgrade Guide

# 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 Installing WebLogic Platform 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>`

5. 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 Verify the upgrade of ACLs by: and Securing WebLogic Resources.

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

- 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: Create a WebLogic Server 8.1 Domain and Security Realm

Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.

1. In WebLogic Server 8.1, run the Configuration Wizard to create a WebLogic Server 8.1 domain called `mydomain`, by accepting most of the defaults.

Note: Accept all the defaults in the Configuration Wizard to create the WebLogic Server 8.1 domain, with the exception of the username and password combination that is used to boot the server. This username and password combination must be in your LDAP server, and the user must be a member of the `Administrators` group.

Step-by-step instructions for using the Configuration Wizard are in Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.

2. Start the WebLogic Server 8.1 instance called `myserver`.
3. Log into the WebLogic Server 8.1 Administration Console.
4. In the left pane of the WebLogic Server 8.1 Administration Console, expand Security —> Realms.

The Realms node expands to show the `myrealm` security realm, which has been configured for you as part of creating the Weblogic Server 8.1 domain.

#### 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 Verify the upgrade of ACLs by: and Securing WebLogic Resources.

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

- 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: Create a WebLogic Server 8.1 Domain and Security Realm

Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.

1. In WebLogic Server 8.1, run the Configuration Wizard to create a WebLogic Server 8.1 domain called `mydomain`, by accepting most of the defaults.

Note: You can accept all the defaults in the Configuration Wizard to create the WebLogic Server 8.1 domain, with the exception of the username and password combination that is used to boot the server. This username and password combination must have the correct privileges to be able to restart the WebLogic Server 8.1 instance. (It need not be the Administrator account.)

Step-by-step instructions for using the Configuration Wizard are in Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.

Warning: If you do not use the Configuration Wizard to create your WebLogic Server 8.1 domain, you will not be able to create the Realm Adapter Authentication provider (in Step 2: Configure a Realm Adapter Authentication Provider) without first copying over your 6.x `filerealm.properties` file.

2. Start the WebLogic Server 8.1 instance called `myserver`.
3. Log into the WebLogic Server 8.1 Administration Console.
4. In the left pane of the WebLogic Server 8.1 Administration Console, expand Security —> Realms.

The Realms node expands to show the `myrealm` security realm, which has been configured for you as part of creating the Weblogic Server 8.1 domain.

#### 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 Verify the upgrade of ACLs by: and Securing WebLogic Resources.

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

- 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: Create a WebLogic Server 8.1 Domain and Security Realm

Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.

1. In WebLogic Server 8.1, run the Configuration Wizard to create a WebLogic Server 8.1 domain called `mydomain`, by accepting most of the defaults.

Note: You can accept all the defaults in the Configuration Wizard to create the WebLogic Server 8.1 domain, but you must be logged into a Unix machine.

Step-by-step instructions for using the Configuration Wizard are in Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.

Warning: If you do not use the Configuration Wizard to create your WebLogic Server 8.1 domain, you will not be able to create the Realm Adapter Authentication provider (in Step 2: Configure a Realm Adapter Authentication Provider) without first copying over your 6.x `filerealm.properties` file.

2. Start the WebLogic Server 8.1 instance called `myserver`.
3. Log in to the WebLogic Server 8.1 Administration Console.
4. In the left pane of the WebLogic Server 8.1 Administration Console, expand Security —> Realms.

The Realms node expands to show the `myrealm` security realm, which has been configured for you as part of creating the Weblogic Server 8.1 domain.

#### 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 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: 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: 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: Create a WebLogic Server 8.1 Domain and Security Realm

Note: If you are running WebLogic Server 6.x and 8.1 on the same machine, be sure to stop your WebLogic Server 6.x instance before following these instructions.

1. In WebLogic Server 8.1, run the Configuration Wizard to create a WebLogic Server 8.1 domain called `mydomain`, by accepting all of the defaults.

For step-by-step instructions for the Configuration Wizard, see Creating and Configuring Domains Using the Configuration Wizard in Configuring and Managing WebLogic Server.

2. Start the WebLogic Server 8.1 instance called `myserver`.
3. Log into the WebLogic Server 8.1 Administration Console.
4. In the left pane of the WebLogic Server 8.1 Administration Console, expand Security —> Realms.

The Realms node expands to show the `myrealm` security realm, which as been configured for you as part of creating the Weblogic Server 8.1 domain.

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

### 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 Default Security Policies in Securing WebLogic Resources for more information.

Note: Be sure you have upgraded your WebLogic Server 6.x domain to a WebLogic Server 8.1 domain and have upgraded your WebLogic Server 6.x security realm to a WebLogic Server 8.1 security realm before following these instructions. For instructions, see Upgrading Your WebLogic Server 6.x Domain to Version 8.1 and Upgrading Your WebLogic Server 6.x Security Realms to 8.1.

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: The ACLs and permissions that have been upgraded to Weblogic Server 8.x from WebLogic Server 6.x are those listed in the `filerealm.properties` files from the `examples` and `petstore` domains. These are also listed in Listing 3-1 and Listing 3-2.

Listing 3-1 fileRealm.properties from 6.x examples Domain

>     acl.modify.weblogic.jndi.weblogic.fileSystem=everyone
>     user.j2ee=0xe22513c99d9279bdf9318894033ef310b9aa830f
>     acl.lookup.weblogic.jndi.weblogic.fileSystem=everyone
>     acl.lookup.weblogic.jndi.weblogic.ejb=system,everyone
>     acl.lookup.weblogic.jndi=system,everyone
>     acl.list.weblogic.jndi.weblogic.rmi=system,everyone
>     acl.lockServer.weblogic.admin=system,guest
>     acl.shutdown.weblogic.admin=system,guest
>     group.gold=
>     acl.boot.weblogic.server=system,everyone
>     user.jps_admin=0xcc0b7594b451623dd59a3db8148de6984c60ac74
>     acl.list.weblogic.jndi.weblogic.fileSystem=everyone
>     acl.lookup.weblogic.jndi.weblogic=system,everyone
>     acl.modify.weblogic.jndi.weblogic.rmi=system,everyone
>     acl.modify.weblogic.jndi.weblogic=system,everyone
>     acl.list.weblogic.jndi.weblogic=system,everyone
>     acl.lookup.weblogic.management=system,everyone
>     group.cust=j2ee
>     acl.modify.weblogic.management=system,everyone
>     acl.findMBeans.weblogic.admin=Administrators
>     group.Administrators=system
>     group.admin=jps_admin
>     acl.lookup.weblogic.jndi.weblogic.rmi=system,everyone
>     acl.list.weblogic.jndi=system,everyone
>     acl.modify.weblogic.admin.acl=system,guest
>     acl.list.weblogic.jndi.weblogic.ejb=system,everyone
>     acl.modify.weblogic.jndi=system,everyone
>     acl.write.managedObject=system,guest
>     acl.reserve.weblogic.jdbc.connectionPool.demopool=system,everyone
>     acl.read.managedObject=system,guest
>     acl.admin.weblogic.jdbc.connectionPoolcreate=system,guest
>     user.system=0xc4d441a2bdd9c4bba6029d63066781512326d355
>     acl.unlockServer.weblogic.admin=system,guest
>     acl.reset.weblogic.jdbc.connectionPool=system
>     acl.execute.weblogic.servlet=everyone
>     acl.modify.weblogic.jndi.weblogic.ejb=system,everyone

Listing 3-2 fileRealm.properties from 6.x petstore Domain

>     acl.modify.weblogic.jndi.weblogic.fileSystem=everyone
>     acl.lookup.weblogic.jndi.weblogic.fileSystem=everyone
>     user.support=0xa227185fac962e564de4796154a80757860e32d4
>     acl.lookup.weblogic.jndi.weblogic.ejb=system,newdbuSer,NEWDBUSER,everyone
>     acl.lookup.weblogic.jndi=system,newdbuSer,NEWDBUSER,everyone
>     acl.list.weblogic.jndi.weblogic.rmi=system,newdbuSer,NEWDBUSER,everyone
>     acl.create.weblogic.jms.ConnectionConsumer=guest
>     acl.lockServer.weblogic.admin=system,newdbuSer,NEWDBUSER,guest
>     acl.reserve.weblogic.jdbc.connectionPool.oraclepool=system,newdbuSer,NEWDBUSER,everyone
>     acl.shutdown.weblogic.admin=system,newdbuSer,NEWDBUSER,guest
>     acl.boot.weblogic.server=vlatas,system,newdbuSer,NEWDBUSER,everyone
>     acl.list.weblogic.jndi.weblogic.fileSystem=everyone
>     acl.lookup.weblogic.jndi.weblogic=system,newdbuSer,NEWDBUSER,everyone
>     acl.modify.weblogic.jndi.weblogic.rmi=system,newdbuSer,NEWDBUSER,everyone
>     acl.modify.weblogic.jndi.weblogic=system,newdbuSer,NEWDBUSER,everyone
>     acl.list.weblogic.jndi.weblogic=system,newdbuSer,NEWDBUSER,everyone
>     acl.lookup.weblogic.management=system,newdbuSer,NEWDBUSER,everyone
>     acl.modify.weblogic.management=system,newdbuSer,NEWDBUSER,everyone
>     acl.findMBeans.weblogic.admin=Administrators
>     group.Administrators=system
>     acl.lookup.weblogic.jndi.weblogic.rmi=system,newdbuSer,NEWDBUSER,everyone
>     acl.list.weblogic.jndi=system,newdbuSer,NEWDBUSER,everyone
>     acl.modify.weblogic.admin.acl=vlatas,system,newdbuSer,NEWDBUSER,guest
>     acl.list.weblogic.jndi.weblogic.ejb=system,newdbuSer,NEWDBUSER,everyone
>     acl.modify.weblogic.jndi=system,newdbuSer,NEWDBUSER,everyone
>     acl.frob.aclexample=joeuser
>     acl.write.managedObject=system,newdbuSer,NEWDBUSER,guest
>     acl.reserve.weblogic.jdbc.connectionPool.demopool=system,newdbuSer,NEWDBUSER,everyone
>     user.joeuser=0x5923f72dc88665f59c119a2a965897fc28a2feaa
>     acl.read.managedObject=system,newdbuSer,NEWDBUSER,guest
>     acl.admin.weblogic.jdbc.connectionPoolcreate=system,newdbuSer,NEWDBUSER,guest
>     user.system=0xfafe4ee933bf59e193de3a8a506a57ddd2364943
>     acl.unlockServer.weblogic.admin=system,newdbuSer,NEWDBUSER,guest
>     acl.reset.weblogic.jdbc.connectionPool=system
>     acl.execute.weblogic.servlet=everyone
>     acl.modify.weblogic.jndi.weblogic.ejb=system,newdbuSer,NEWDBUSER,everyone

## 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 Private Keys and Digital Certificates

### 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. If you choose not to use a keystore, a password is required in order to use the private key and associated digital certificate with this release of WebLogic Server. For more information, see Configuring SSL in Managing WebLogic Security.

For the purpose of backward compatibility, the WebLogic Server 8.1 Administration Console provides mechanisms for configuring SSL using file-based identity and trust. However, you should upgrade to keystores as soon as possible.

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

### Upgrading Private Keys and Digital Certificates

You can still use private keys and digital certificates used with WebLogic Server 6.1 with WebLogic Server 8.1. Convert the private key and digital certificate from privacy-enhanced mail (PEM) format to distinguished encoding rules (DER) format. For more information, see the description of the der2pem utility in Using WebLogic Server Java Utilities.

After converting the files, ensure the digital certificate file has the
`-----BEGIN CERTIFICATE----` header and the`-----END CERTIFICATE-----` footer. Otherwise, the digital certificate will not work with WebLogic Server 8.1.

# 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 60
- 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, you must use the new deployment APIs. If your application is previously deployed in 6.x and you are starting your server, the applications are deployed with one-phase deployment. The `weblogic.deploy` and `weblogic.refresh` command line utilities and the `weblogic.management.tools.WebAppComponentRefreshTool` and are deprecated in 8.1.

See Deprecated APIs and Features for information on deprecated MBean attributes and operations.

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

Note: Evaluate the amount of memory available with the amount you require as, assigning a very high value to the max-beans-in-cache parameter may result in an OutOfMemoryError. The amount of memory cache required can be calculated as the number of beans in the cache times the size of the EJB.

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

## jCO M

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 the Starting and Configuring the WebLogic JRockit JVM section for the appropriate version of the JRockit documentation.

For JRockit platform and user information, see the appropriate version of the JRockit User Guide.

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

####

Table 3-1 Default 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

Previous versions of this document and various other sample documents erroneously described using `weblogic.management.Admin.getInstance().getAdminMBeanHome()` as a way to look up the `MBeanHome` interface on the Administration Server.

However, the `weblogic.management.Admin` class is not public. Instead of using this non-public class, use JNDI to retrieve `MBeanHome`. See Determining the Active Domain and Servers in Programming WebLogic Server JMX Services.

## 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 Ap plication 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:``

####

Table 3-2 Conversion Tool Arguments

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, you must modify the reference object that connects WebLogic Tuxedo Connector instances to Tuxedo CORBA applications. Tuxedo CORBA objects now use the server name to reference remote WebLogic Tuxedo Connector objects. Earlier releases used the `DOMAINID`.

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 3-3 Domain Configuration File

>     *DM_RESOURCES
>          VERSION=U22

>     *DM_LOCAL_DOMAINS
>          TDOM1 	GWGRP=SYS_GRP
>          TYPE=TDOMAIN
>          DOMAINID="TDOM1"
>          BLOCKTIME=20
>          MAXDATALEN=56
>          MAXRDOM=89

>     *DM_REMOTE_DOMAINS
>          TDOM2 TYPE=TDOMAIN
>          DOMAINID="TDOM2"

>     *DM_TDOMAIN
>          TDOM1 NWADDR="<network address of Tuxedo domain:port>"
>          TDOM2 NWADDR="<network address of WTC domain:port>"

>     *DM_REMOTE_SERVICES
>     "//servername"

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, you must 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, you must set a password key using the WebLogic Server PasswordKey property. For more information on how to generate passwords, see Configuring a WTCPassword MBean .

- `-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, you must upgrade Web services created in version 6.1 to run on version 8.1.

The WebLogic Web services client API included in WebLogic Server 6.1 of has been deprecated and you cannot use it to invoke 8.1 Web services. WebLogic Server 8.1 includes a new client API, based on the Java API for XML-based RPC (JAX-RPC).

For detailed information on upgrading a 6.1 WebLogic Web service to 8.1, see Upgrading 6.1 WebLogic Web Services to 8.1.

For examples of using JAX-RPC to invoke WebLogic Web services, see Invoking Web Services.

For general information on the differences between 6.1 and 8.1 Web services, see Overview of WebLogic Web Services.

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