BEA WebLogic Server 7 User Manual

BEA

WebLogic Server

™

BEA WebLogic Server 7.0 Upgrade Guide

Release 7.0 Document Date: June 2002 Revised: June 28, 2002

Restricted Rights Legend

This software and documentation is subject to and made available only pursuant to the terms of the BEA Systems License Agreement and may be used or copied only in accordance with the terms of that agreement. It is against the law to copy the software except as specifically allowed in the agreement. This document may not, in whole or in part, be copied photocopied, reproduced, translated, or reduced to any electronic medium or machine readable form without prior consent, in writing, from BEA Systems, Inc.

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the BEA Systems License Agreement and in subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clause at FAR

52.227-19; subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS

252.227-7013, subparagraph (d) of the Commercial Computer Software--Licensing clause at NASA FAR supplement 16-52.227-86; or their equivalent.

Information in this document is subject to change without notice and does not represent a commitment on the part of BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE.

Trademarks or Service Marks

BEA, Jolt, Tuxedo, and WebLogic are registered trademarks of BEA Systems, Inc. BEA Builder, BEA Campaign Manager for WebLogic, BEA eLink, BEA Manager, BEA WebLogic Commerce Server, BEA WebLogic Enterprise, BEA WebLogic Enterprise Platform, BEA WebLogic Express, BEA WebLogic Integration, BEA WebLogic Personalization Server, BEA WebLogic Platform, BEA WebLogic Portal, BEA WebLogic Server, BEA WebLogic Workshop and How Business Becomes E-Business are trademarks of BEA Systems, Inc.

All other trademarks are the property of their respective companies. BEA WebLogic Server 7.0 Upgrade Guide

Part Number Date Software Version

N/A June 28, 2002 BEA WebLogic Server

Version 7.0

About This Document

Audience.............................................................................................................. ix

e-docs Web Site................................................................................................... ix

How to Print the Document...................................................................................x

Documentation Conventions ............................................................................... xi

1. Upgrading WebLogic Server 6.x to Version 7.0

Upgrading Your WebLogic Server Configuration: Main Steps........................ 1-2

Modifying Startup Scripts .................................................................................1-3

Understanding the WebLogic Server 7.0 Directory Structure .......................... 1-4

Porting an Application from WebLogic Server 6.x to WebLogic Server 7.0 ... 1-4

Upgrading Security............................................................................................ 1-6

Booting WebLogic Server in Compatibility Security ................................1-7

ACLs on MBeans....................................................................................... 1-7

Upgrading from Compatibility Security to WebLogic Server 7.0 Security.....

1-8

Security Realms.......................................................................................... 1-9

Guest User................................................................................................ 1-11

password.ini File ...................................................................................... 1-11

Upgrading the SSL Protocol .................................................................... 1-12

Creating a Trusted CA Keystore....................................................... 1-12

Using CertAuthenticator in Compatibility Security.......................... 1-13

Cipher Suites..................................................................................... 1-14

Upgrading WebLogic Tuxedo Connector ....................................................... 1-15

Start the WebLogic Tuxedo Connector....................................................1-15

Convert WebLogic Tuxedo Connector XML Configuration Files .......... 1-16

BEA WebLogic Server 7.0 Upgrade Guide iii

Update Inbound RMI-IIOP Applications.................................................1-17

Authenticate Remote Users ......................................................................1-19

ACL Policy is LOCAL......................................................................1-19

ACL Policy is Global ........................................................................1-20

Set WebLogic Tuxedo Connector Properties ...........................................1-20

Additional Upgrade Procedures and Information............................................1-21

ant.jar........................................................................................................1-22

Apache Xalan XML Transformer ............................................................ 1-22

Apache Xerces XML Parser.....................................................................1-23

Applications Directory ............................................................................. 1-23

Deployment ..............................................................................................1-24

EJB 2.0 .....................................................................................................1-25

weblogic.management.configuration.EJBComponentMBean Changes ..

1-26

max-beans-in-cache Parameter .........................................................1-26

Fully Qualified Path Expressions......................................................1-27

jCOM........................................................................................................ 1-27

JDBC ........................................................................................................1-27

JMS...........................................................................................................1-28

JMX ..........................................................................................................1-28

Jolt Java Client .........................................................................................1-28

JSP ............................................................................................................1-29

Load Order for Startup Classes ................................................................1-29

Managed Servers ......................................................................................1-29

MBean API Change.................................................................................. 1-30

Security.....................................................................................................1-30

Guest and <Anonymous> Users........................................................ 1-30

Servlets .....................................................................................................1-31

Thread Pool Size.......................................................................................1-31

Web Applications .....................................................................................1-32

WebLogic Server Clusters on Solaris.......................................................1-33

Web Services............................................................................................1-33

Writable config.xml File ..........................................................................1-33

Deprecated APIs and Features..................................................................1-34

Removed APIs and Features ....................................................................1-36

iv BEA WebLogic Server 7.0 Upgrade Guide

2. Upgrading WebLogic Server 4.5 and 5.1 to Version 7.0

Upgrading Your WebLogic Server Configuration: Main Steps........................ 2-2

Upgrading WebLogic Server License Files ......................................................2-4

Converting a WebLogicLicense.class License........................................... 2-4

Converting a WebLogicLicense.XML License ......................................... 2-4

Converting the weblogic.properties File to XML Files..................................... 2-5

Classloading in WebLogic Server 7.0 ...............................................................2-8

Modifying Startup Scripts .................................................................................2-8

WebLogic Server 7.0 J2EE Application Types.................................................2-9

Converting and Porting Your Existing Applications into Web Applications ... 2-9

Web Applications Directory Structure..................................................... 2-10

XML Deployment Descriptors................................................................. 2-11

WAR Files................................................................................................2-12

Deploying Web Applications................................................................... 2-12

Session Porting......................................................................................... 2-13

JavaServer Pages (JSPs) and Servlets ......................................................2-14

Porting a Simple Servlet from WebLogic Server 5.1 to WebLogic Server 7.0

2-15

Porting and Converting Enterprise JavaBeans Applications........................... 2-16

EJB Porting Considerations ..................................................................... 2-17

EJB Porting Recommendations................................................................ 2-18

Steps for Porting a 1.0 EJB from WebLogic Server 4.5.x to WebLogic Server

7.0...................................................................................................... 2-20

Steps for Porting a 1.1 EJB from WebLogic Server 5.1 to WebLogic Server

7.0...................................................................................................... 2-21

Steps for Converting an EJB 1.1 to an EJB 2.0........................................ 2-22

Porting EJBs from Other J2EE Application Servers................................2-23

Creating an Enterprise Application .................................................................2-23

Understanding J2EE Client Applications........................................................ 2-24

Upgrading JMS................................................................................................ 2-25

Upgrading Oracle ............................................................................................ 2-25

Additional Porting and Deployment Considerations....................................... 2-26

Applications and Managed Servers.......................................................... 2-27

Deployment .............................................................................................. 2-27

Plug-ins.....................................................................................................2-27

BEA WebLogic Server 7.0 Upgrade Guide v

FileServlet.................................................................................................2-28

Internationalization (I18N).......................................................................2-28

Java Transaction API (JTA) .....................................................................2-28

Java Database Connectivity (JDBC) ........................................................2-29

JSP ............................................................................................................2-29

Error Handling...................................................................................2-29

Null Attributes...................................................................................2-30

JVM ..........................................................................................................2-30

RMI...........................................................................................................2-30

Security.....................................................................................................2-31

Upgrading to the New Security Architecture....................................2-31

Digital Certificates Generated by the Certificate Servlet.................. 2-32

Private Keys and Digital Certificates ................................................2-32

Session Porting ......................................................................................... 2-33

Standalone HTML and JSPs.....................................................................2-33

Web Components .....................................................................................2-34

Wireless Application Protocol Applications ............................................2-35

Writable config.xml File ..........................................................................2-35

XML 7.0 Parser and Transformer ............................................................2-36

Deprecated APIs and Features..................................................................2-36

Removed APIs and Features ....................................................................2-37

A. The weblogic.properties Mapping Table

B. Upgrading the Pet Store Application and the Examples Server

Terms Used in This Document......................................................................... B-1

Upgrading the Pet Store Application From WebLogic 6.1 Service Pack 3 to

WebLogic Server 7.0................................................................................. B-2

Install WebLogic Server 7.0...................................................................... B-2

Set Up the WebLogic Server 7.0 Environment with Your 6.1 Service Pack 3

Domain Configuration........................................................................ B-3

Fix JSP Parsing Errors........................................................................ B-4

Rebuild Pet Store................................................................................ B-6

startPetstore.cmd script used to boot WebLogic Server 6.1 Service Pack

3................................................................................................... B-7

above-listed startPetstore.cmd script modified to boot WebLogic Server

vi BEA WebLogic Server 7.0 Upgrade Guide

7.0 ................................................................................................B-9

config.xml file used for WebLogic Server 6.1 Service Pack 3.........B-12

above-listed config.xml file used for WebLogic Server 7.0 .............B-15

Start the Pet Store Application on WebLogic Server 7.0.........................B-19

Upgrading the WebLogic 6.0 Service Pack 2 Examples Server to WebLogic

Server 7.0 .................................................................................................B-19

Install WebLogic Server 7.0.....................................................................B-19

Set Up the WebLogic Server 7.0 Environment with Your 6.0 Service Pack 2

Domain Configuration ......................................................................B-20

setExamplesEnv.cmd script used to boot a WebLogic 6.0 Service Pack 2

Examples Server ........................................................................B-21

above-listed setExamplesEnv.cmd script modified to boot a WebLogic

7.0 Examples Server ..................................................................B-23

startExamplesServer.cmd script used to boot a WebLogic 6.0 Service

Pack 2 Examples Server ............................................................B-25

above-listed startExamplesServer.cmd script modified to boot a

WebLogic 7.0 Examples Server ................................................B-26

Start the Examples Server on WebLogic Server 7.0................................B-28

Upgrading the WebLogic 6.1 Service Pack 2 Examples Server to WebLogic

Server 7.0 .................................................................................................B-29

Install WebLogic Server 7.0.....................................................................B-29

Set Up the WebLogic Server 7.0 Environment with Your 6.1 Service Pack 2

Domain Configuration ......................................................................B-30

setExamplesEnv.cmd script used to boot a WebLogic 6.1 Service Pack 2

Examples Server ........................................................................B-31

above-listed setExamplesEnv.cmd script modified to boot WebLogic

Server 7.0...................................................................................B-33

startExamplesServer.cmd script used to boot a WebLogic 6.1 Service

Pack 2 Examples Server ............................................................B-34

above-listed startExamplesServer.cmd script modified to boot

WebLogic Server 7.0 .................................................................B-37

Start the Examples Server on WebLogic Server 7.0................................B-39

BEA WebLogic Server 7.0 Upgrade Guide vii

viii BEA WebLogic Server 7.0 Upgrade Guide

About This Document

This document provides procedures and other information you need to upgrade earlier versions of BEA WebLogic Server to WebLogic 7.0. It also provides information about moving applications from an earlier version of WegLogic Server to 7.0.

The document is organized as follows:

 Chapter 1, “Upgrading WebLogic Server 6.x to Version 7.0,” describes how to

upgrade to WebLogic Server 7.0 from WebLogic Server 6.x.

 Chapter 2, “Upgrading WebLogic Server 4.5 and 5.1 to Version 7.0,” describes

how to upgrade to WebLogic Server 7.0 from WebLogic Server 4.5 or 5.1.

 Appendix A, “The weblogic.properties Mapping Table,” shows which

config.xml, web.xml, or weblogic.xml attribute handles the function

formerly performed by

Audience

weblogic.properties properties.

This document is written for all users of WebLogic Server 4.5, 5.1, 6.0, and 6.1 who want to upgrade to WebLogic Server 7.0.

e-docs Web Site

BEA product documentation is available on the BEA corporate Web site. From the BEA Home page, click on Product Documentation.

BEA WebLogic Server 7.0 Upgrade Guide ix

How to Print the Document

You can print a copy of this document from a Web browser, one main topic at a time, by using the File

A PDF version of this document is available on the WebLogic Server documentation Home page on the e-docs Web site (and also on the documentation CD). You can open the PDF in Adobe Acrobat Reader and print the entire document (or a portion of it) in book format. To access the PDFs, open the WebLogic Server documentation Home page, click Download Documentation, and select the document you want to print.

Adobe Acrobat Reader is available at no charge from the Adobe Web site at

http://www.adobe.com.

→Print option on your Web browser.

Contact Us!

Your feedback on BEA documentation is important to us. Send us e-mail at

docsupport@bea.com if you have questions or comments. Your comments will be

reviewed directly by the BEA professionals who create and update the documentation.

In your e-mail message, please indicate the software name and version you are using, as well as the title and document date of your documentation. If you have any questions about this version of BEA WebLogic Server, or if you have problems installing and running BEA WebLogic Server, contact BEA Customer Support through BEA WebSupport at http://www.bea.com. You can also contact Customer Support by using the contact information provided on the Customer Support Card, which is included in the product package.

When contacting Customer Support, be prepared to provide the following information:

 Your name, e-mail address, phone number, and fax number

 Your company name and company address

 Your machine type and authorization codes

 The name and version of the product you are using

x BEA WebLogic Server 7.0 Upgrade Guide

 A description of the problem and the content of pertinent error messages

Documentation Conventions

The following documentation conventions are used throughout this document.

Convention Usage

Ctrl+Tab Keys you press simultaneously.

italics Emphasis and book titles.

monospace text

monospace italic text

UPPERCASE TEXT

{ }

Code samples, commands and their options, Java classes, data types, directories, and file names and their extensions. Monospace text also indicates text that you enter from the keyboard.

Examples:

import java.util.Enumeration; chmod u+w * config/examples/applications .java config.xml float

Variables in code. Example:

String CustomerName;

Device names, environment variables, and logical operators. Examples: LPT1 BEA_HOME OR

A set of choices in a syntax line.

BEA WebLogic Server 7.0 Upgrade Guide xi

Convention Usage

[ ]

...

. . .

Optional items in a syntax line. Example:

java utils.MulticastTest -n name -a address

[-p portnumber] [-t timeout] [-s send]

Separates mutually exclusive choices in a syntax line. Example:

java weblogic.deploy [list|deploy|undeploy|update] password {application} {source}

Indicates one of the following in a command line:

 An argument can be repeated several times in the command line.  The statement omits additional optional arguments.  You can enter additional parameters, values, or other information

Indicates the omission of items from a code example or from a syntax line.

xii BEA WebLogic Server 7.0 Upgrade Guide

CHAPTER

1 Upgrading WebLogic

Server 6.x to Version

7.0

Upgrading WebLogic Server 6.x to version 7.0, under the simplest circumstances, involves changing your WebLogic Server start command scripts and environment settings. In some cases, it is necessary to move your domain directory. Sometimes, upgrading requires 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 7.0:

 “Upgrading Your WebLogic Server Configuration: Main Steps” on page 1-2

 “Modifying Startup Scripts” on page 1-3

 “Understanding the WebLogic Server 7.0 Directory Structure” on page 1-4

 “Porting an Application from WebLogic Server 6.x to WebLogic Server 7.0” on

page 1-4

 “Upgrading Security” on page 1-6

 “Upgrading WebLogic Tuxedo Connector” on page 1-15

 “Additional Upgrade Procedures and Information” on page 1-21

For instructions on how to upgrade the Pet Store application from WebLogic Server

6.1 to WebLogic Server 7.0 and how to upgrade the WebLogic 6.0 and 6.1 Examples Servers to WebLogic Server 7.0, see “Upgrading the Pet Store Application and the

Examples Server”.

BEA WebLogic Server 7.0 Upgrade Guide 1-1

1 Upgrading WebLogic Server 6.x to Version 7.0

For information on upgrading to WebLogic Platform 7.0 (7.0.0.1), see the Upgrading section of the WebLogic Server FAQs.

Note: Throughout this document “upgrade” refers to upgrading to a later version of

WebLogic Server and “port” refers to moving your applications from an earlier version of WebLogic Server to a later version.

Upgrading Your WebLogic Server Configuration: Main Steps

Take the following steps to upgrade from WebLogic Server 6.x to WebLogic Server

7.0:

1. Make a backup copy of your 6.x domain before you begin the upgrade procedure. After you start the server using WebLogic Server 7.0 classes, you cannot downgrade to 6.x.

2. Install WebLogic Server 7.0. See the the Installation Guide.

Note: The installer will prevent you from installing the new version directly over

the old version. You must select a new directory location.

3. Modify your 6.x startup scripts to work with WebLogic Server 7.0. See

“Modifying Startup Scripts” on page 1-3.

4. Ensure that you have considered differences in the WebLogic Server 7.0 directory structure that may require you to make file location changes before startup. See “Understanding the WebLogic Server 7.0 Directory Structure” on

page 1-4.

5. Port your applications to WebLogic Server 7.0. See “Porting an Application from

WebLogic Server 6.x to WebLogic Server 7.0” on page 1-4.

6. If necessary, perform other upgrade procedures as described in “Upgrading

Security” on page 1-6, “Upgrading WebLogic Tuxedo Connector” on page 1-15,

and “Additional Upgrade Procedures and Information” on page 1-21.

1-2 BEA WebLogic Server 7.0 Upgrade Guide

To upgrade a cluster of servers, follow the above steps for each server and then follow the steps outlined in Setting Up WebLogic Clusters in Using WebLogic Server Clusters. In cases where you invoke an application by using RMI/T3 or RMI/IIOP, WebLogic Server 6.1 and 7.0 are interoperable. Within a domain, however, all servers must be of the same version.

For information on upgrading WebLogic Server license files, see Upgrading Licenses

from Previous WebLogic Server Releases in the Installation Guide.

Modifying Startup Scripts

If you used WebLogic Server startup scripts with a previous version of the product, modify them to work with WebLogic Server 7.0.

Modify the startup scripts as described here. For another example of how to modify the startup scripts, see “Upgrading the Pet Store Application and the Examples Server”.

Modify the startup scripts as described here.

Modifying Startup Scripts

1. Modify

2. Modify WL_HOME

3. Modify PATH

4. Modify CLASSPATH

bea.home property

to point to your BEA home directory containing the WebLogic Server 7.0. For example:

-Dbea.home=C:\bea700

must point to your WebLogic Server 7.0 installation directory. For example:

WL_HOME=c:\bea700\weblogic700

so that it includes your %WL_HOME% 7.0 home. For example:

PATH=%WL_HOME%\bin;%PATH%

so that it points to the WebLogic Server 7.0 classes. For example:

CLASSPATH=%WL_HOME%\lib\weblogic_sp.jar;%WL_HOME%\lib\weblog ic.jar

BEA WebLogic Server 7.0 Upgrade Guide 1-3

license.bea file for

1 Upgrading WebLogic Server 6.x to Version 7.0

5. Modify or eliminate any WebLogic Server 6.x startup script directory structure tests. For example, if your script tries to verify a relative path, either fix the directory structure test or remove it.

WebLogic Server 7.0 installs the JVM, JDK 1.3.1_02, with the server installation. The

setenv.sh scripts provided with the server all point to the JVM. The latest

information regarding certified JVMs is available at the Certifications Page.

Understanding the WebLogic Server 7.0 Directory Structure

The directory structure in WebLogic Server 7.0 is different from that of 6.x. For complete information on the updated directory structure see Understanding the

WebLogic Server Directory Structure in Performing Post-Installation Tasks in the

Installation Guide.

If you are booting your WebLogic Server 6.x domain with the WebLogic Server 7.0 environment, the new directory structure is created automatically. However, if you have custom tools or scripts that rely on the WebLogic Server 6.x domain directory structure, you need to update those tools relative to the new directory structure. Similarly, if you have a scripted tool for creating domains in the WebLogic Server 6.x environment, you will have to change those scripts. It is best to use the Configuration

Wizard which can be scripted.

Porting an Application from WebLogic Server 6.x to WebLogic Server 7.0

Note: Throughout this document, the directory of the new WebLogic Server 7.0

domain that is created is referred to as

Use the following steps to port WebLogic 6.x applications on WebLogic Server 7.0:

1-4 BEA WebLogic Server 7.0 Upgrade Guide

domain.

Porting an Application from WebLogic Server 6.x to WebLogic Server 7.0

1. If you have not already installed WebLogic Server 7.0, do so now. See the

Installation Guide for more information.

Note: Installing the new version in the exact location of the old version is

explicitly prohibited by the installer.

2. Each 6.x and 7.0 domain must have its own separate directory. It is not possible to have multiple

a. For each 6.x configuration domain that you wish to port to WebLogic Server

7.0, copy the Exclude any directories that begin with a dot (“.”), which are files or directories that WebLogic Server has created for internal use.

This directory is the location of your new domain and will contain all of your configuration information for that domain. If your 6.x config directory is not located in the WebLogic Server 6.x distribution, you may re-use your WebLogic 6.x configuration in WebLogic Server 7.0.

config.xml files in the same directory.

/config/domain directory to a directory location of your choice.

b. Identify deployment descriptor files (

web.xml and weblogic.xml), because

those files may contain file paths to items such as the Java compiler or external files. WebLogic Server configurations rely on a number of files that may be stored on the file system. Typically, these files are persistence repositories (log files, file-based repositories, etc.) or utilities (Java compiler). These files can be configured using fully qualified or relative paths.

If all external files are defined using relative paths and are located in or below the domain directory, skip the reamainder of this step.

For external files that are defined using relative paths that are located outside the domain directory, re-create the directory structure relative to the new config directory and copy the associated files into the new directories. For external files that are defined using fully qualified paths, determine whether it is appropriate to re-use these files in the WebLogic Server 7.0 deployment.

For example, log files and persistence stores can be re-used; however, you may want to update utilities such as the Java compiler to use the latest version. For files that should be updated, use the WebLogic Server 6.x Administration Console to configure the appropriate attribute to use the new file or utility before proceeding to the next step.

3. If you have not already edited the server start scripts, do so now. See “Modifying

Startup Scripts” on page 1-3 for instructions.

BEA WebLogic Server 7.0 Upgrade Guide 1-5

1 Upgrading WebLogic Server 6.x to Version 7.0

4. When you deploy applications to WebLogic Server 7.0, use the Administration Console or deployment protocol. The older, WebLogic Server 6.x deployment protocol, utilities, and API are deprecated in WebLogic Server 7.0

Note: WebLogic Server 7.0 will not deploy an application that has errors in its

weblogic.Deployer utility to deploy using the new two-phase

deployment descriptor. Previous versions of WebLogic Server would deploy an application that had errors in its deployment descriptor.

Upgrading Security

WebLogic Server 7.0 has a new security architecture. For specific questions and answers, see the security section of the Introduction to WebLogic Security.

WebLogic Server 7.0 detects whether you are upgrading from an earlier WebLogic Server version or whether you are a new customer starting with 7.0. If you are upgrading from WebLogic Server 6.x, WebLogic Server 7.0 runs in Compatibility security, meaning that it 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 7.0 offers improved and expanded security features - users are encouraged to upgrade their security configuration. See the following list of issues and procedures:

 “Booting WebLogic Server in Compatibility Security” on page 1-7

 “ACLs on MBeans” on page 1-7

 “Upgrading from Compatibility Security to WebLogic Server 7.0 Security” on

page 1-8

 “Security Realms” on page 1-9

 “Guest User” on page 1-11

 “password.ini File” on page 1-11

 “Upgrading the SSL Protocol” on page 1-12

1-6 BEA WebLogic Server 7.0 Upgrade Guide

Upgrading Security

Note: The WebLogic Server 7.0 examples and PetStore are configured to use the

default security configuration. It is not possible to run the WebLogic Server

7.0 examples and PetStore in Compatibility security.

Booting WebLogic Server in Compatibility Security

In previous releases of WebLogic Server, the File realm was configured by default. Therefore, WebLogic Server could use the File Realm to boot even if there was no security realm defined in the Server in Compatibility security, you need to have either a File realm or an alternative security realm defined in your

If you are unable to boot WebLogic Server in Compatibility security, copy

SerializedSystemini.dat to your new domain folder and then do one of the

following:

 Boot your configuration under WebLogic Server 6.x, letting the server save the

config.xml file, and then port the saved config.xml file to WebLogic Server

7.0.

 Edit your 6.x config.xml file to include the following definitions:

config.xml file. However, in order to run WebLogic

config.xml file. Otherwise, your server may not boot.

ACLs on MBeans

ACLs on MBeans are not supported in WebLogic Server 7.0. For information on protecting MBeans in WebLogic Server 7.0, see Protecting System Administration

Operations in the Administration Guide.

BEA WebLogic Server 7.0 Upgrade Guide 1-7

1 Upgrading WebLogic Server 6.x to Version 7.0

Upgrading from Compatibility Security to WebLogic Server 7.0 Security

If you want to leverage the new security features in WebLogic Server 7.0, you need to upgrade your existing security realm to a WebLogic Server 7.0 security realm. You upgrade by populating the security providers in WebLogic Server 7.0 with your existing user and group information and defining security policies on resources that reflect the ACLs.

During successful booting of your WebLogic Server 6.x configuration, the Compatibility realm is created as the default security realm. The Compatibility realm contains all your 6.x security data. In addition, a default WebLogic Server 7.0 security realm called myrealm is also created. To upgrade, you need to replace the Compatibility realm with myrealm. From within the WebLogic Server Administration Console:

1. Click on 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 on the myrealm node.

3. Click on 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 WebLogic Server to the user replaces the

a. Click on the Security node.

b. Click on the Realms node.

c. Click on the name of the realm you are configuring (for example, myrealm).

d. Click on Groups.

The Groups tab appears. This tab displays the names of all groups defined in the default Authentication provider.

e. Click on the Administrators group on the Groups tab.

1-8 BEA WebLogic Server 7.0 Upgrade Guide

system user. To add a user to the Administrators group:

Administrators group. This

f. Click the Membership tab to add the user who can boot WebLogic Server to the

Administrators group.

g. Click the Apply button to save your changes.

5. Add the users and groups that you had configured in the 6.x security realm to an Authentication provider.

6. Optionally, define roles for your 6.x users and groups. See Securing WebLogic

Resources.

7. Express 6.x ACLs as security policies. See Securing WebLogic Resources.

8. Set myrealm as the default security realm. See Setting the Default Security Realm in Managing WebLogic Security.

9. Reboot WebLogic Server.

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

Security Realms

Upgrading Security

The scope of security realms changed in WebLogic Server 7.0. 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.

In WebLogic Server 7.0, security realms act as a scoping mechanism. Each realm consists of a set of configured security providers, users, groups, roles, and security policies. Authentication and Authorization providers within a security realm offer authentication and authorization services.

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

 Use Compatibility security to access the users, groups, and ACLs configured in

an LDAP, Windows NT, UNIX, RDBMS, or custom security realm. The Realm Adapter Authentication provider in the Compatibility realm can access users, groups, and ACLs stored in a 6.x security realm.

BEA WebLogic Server 7.0 Upgrade Guide 1-9

1 Upgrading WebLogic Server 6.x to Version 7.0

For information about using Compatibility security, see “Booting WebLogic

Server in Compatibility Security” on page 1-7.

 Use the Realm Adapter Authentication provider with the WebLogic Server 7.0

security providers. This option allows you to use the roles and security policies available in WebLogic Server 7.0 while accessing users and groups stored in an LDAP, Windows NT, UNIX or RDBMS security realm. You also have the option of configuring multiple Authentication providers so you can use your existing

6.x security realm while upgrading users and groups to an Authentication provider in WebLogic Server 7.0.

Note: You will not be able to access ACLs stored in the RDBMS realm, if you

configure the Realm Adapter Authentication provider as an authentication provider in a 7.0 security realm. You will have to protect your application resources with roles and security policies.

To use the Realm Adapter Authentication provider in a WebLogic 7.0 security realm:

1. Boot Compatibility security.

2. Ensure that the Realm Adapter Authentication provider in the Compatibility realm is populated with users and groups from your 6.x security realm (check that existing users and groups appear in the Users and Groups table). The user and group information is copied into a

filerealm.properties file.

3. Click on security realm in which you want to use the Realm Adapter Authentication provider (for example, myrealm).

4. Click Providers-->Authentication providers.

5. Configure a Realm Adapter Authentication provider in the security realm. Give the Realm Adapter Authentication provider the same name it had in the Compatibility realm.

6. Set the Control Flag attribute on the Realm Adapter Authentication provider to OPTIONAL.

7. Set the Control Flag attribute on the WebLogic Authentication provider (referred to as the Default Authenticator in the Administration Console) to SUFFICIENT.

8. Add a user that can boot WebLogic Server to the user replaces the

Compatibility Security to WebLogic Server 7.0 Security” on page 1-8.

1-10 BEA WebLogic Server 7.0 Upgrade Guide

system user. For more information, see “Upgrading from

Administrators group. This

Guest User

Upgrading Security

9. Reboot WebLogic Server.

10. Expand the Domains-->Security nodes.

11. Select the General tab.

12. Set the security realm in which you configured the Realm Adapter Authentication provider as the default security realm.

13. Click Apply.

Note: ACLs cannot be upgraded to WebLogic Server 7.0.

The guest user is no longer supplied by default in WebLogic Server 7.0. To use the

guest user, you must run in Compatibility security or define the guest user as a user

in the default Authentication provider for your security realm. For information about defining users, see “Creating Users” in Securing WebLogic Resources.

In WebLogic Server 6.x, the (anonymous user) as a guest user and allowed the guest user access to WebLogic Server resources. In 7.0, WebLogic Server distinguishes between the guest user and an anonymous user. To use the guest user as you did in WebLogic Server 6.x, add the guest user to the default Authentication provider and set the following property when starting WebLogic Server:

-Dweblogic.security.anonymousUserName=guest

Without this command line property, the anonymous user will have the name of

<anonymous>.

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 7.0. It is replaced by

the

boot.properties file, which contains your username and password in an

encrypted format. For more information about using the

guest user identified any unauthenticated user

boot.properties file, see

BEA WebLogic Server 7.0 Upgrade Guide 1-11

1 Upgrading WebLogic Server 6.x to Version 7.0

Creating a Boot Identity File in the Administration Guide. There is no direct upgrade

of the old username.

password.ini file because it contained a clear text password and no

Upgrading the SSL Protocol

This section contains information on how to upgrade the SSL protocol including instructions for creating a trusted CA Keystore, creating a private key Keystore, and using a CertAuthenticator in Compatibility security.

Creating a Trusted CA Keystore

By default in WebLogic Server 7.0, clients check the server’s trusted certificate authority. This check is done whenever a client and server connect using SSL, including when WebLogic Server is acting an a client. For example, when a client is using the SSL protocol to connect to an Apache HTTP Server, the client checks the trusted certificate authorities presented by the server. The client rejects the server's trusted certificate authority if the certificate authority is not trusted by the client. Previous versions of WebLogic Server did not perform this trust validation.

Make the following changes to allow an existing 6.x WebLogic client to use SSL protocol to communicate with a server:

1. Specify the following command-line argument for the client:

-Dweblogic.security.SSL.trustedCAKeyStore=absoluteFilename

where absoluteFilename is the name of the keystore that contains the trusted certificate authority

Note: The file format is a keystore NOT a certificate file. The trusted certificate

authority must be loaded into the keystore.

2. Load the server's trusted certificate authority into the client keystore. To list trusted certificate authorites in the keystore or to load new trusted certificate authorities into the keystore, use the JDK

To add a trusted certificate authority to a keystore, enter the following at a command prompt:

1-12 BEA WebLogic Server 7.0 Upgrade Guide

keytool utility.

Upgrading Security

keytool -import -trustcacerts -alias <some alias name> -file <the

file that contains the trusted CA>

-storepass <your trusted CA Keystore password>

The trusted certificate authority shipped with WebLogic Server is located in

WL_HOME/server/lib/cacerts. Use the following command to add the trusted

certificate authority that is shipped with WebLogic Server to a keystore:

keytool -import -trustcacerts -alias <some alias name> -file <the

file that contains the trusted CA>

-storepass changeit

For more information about keytool, see SUN's website at

http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/keytool.html.

The

trustedCAKeyStore command-line argument defaults to the JDK's

jre/lib/security/cacerts keystore for clients. You can add your CAs to the

JDK's trusted CA keystore and not specify the command-line argument, or you can create your own trusted CA keystore and point to it with the argument.

For two-way SSL or mutual authentication, in addition to performing the previous two steps on the client side, do either of the following steps on the server side:

 Add -Dweblogic.security.SSL.trustedCAKeyStore=absoluteFilename

to the server command line.

-keystore <the trusted CA keystore>

-keystore WL_HOME/server/lib/cacerts

where

absoluteFilename is the name of the trusted CA Keystore

 Set the RootCAKeyStoreLocation attribute when configuring a Keystore

provider.

If you do not load the trusted CA certificate into the trusted CA Keystore, you may have problems using the secure port.

Using CertAuthenticator in Compatibility Security

In WebLogic Server 7.0, the CertAuthenticator is called first, before any username/password authentication. Because this is a change in behavior from WebLogic Server 6.x, a CertAuthenticator written for WebLogic Server 6.x may need to change if clients used both two-way SSL and they supplied a username and password for security credentials.

BEA WebLogic Server 7.0 Upgrade Guide 1-13

1 Upgrading WebLogic Server 6.x to Version 7.0

Using a CertAuthenticator that needs to be changed may result in access being denied in WebLogic Server 7.0, but allowed in WebLogic Server 6.x. To change the CertAuthenticator, have it return are only being used to make an SSL connection.

In WebLogic Server 7.0, X.509 Identity Assertion is turned off by default. If your WebLogic Server 6.x configure the X.509 identity assertion when using Compatibility security. You enable X.509 identity assertion by configuring options on the Realm Adapter Authentication provider. In the WebLogic Server Administration Console while running in Compatibility security:

1. Click on the Security node.

2. Click on the Realms node.

3. Click on the CompatibilityRealm node.

4. Click on the Providers node.

5. Click on the Authentication Providers node.

6. Click on the RealmAdapterAuthenticator node.

The General tab appears.

config.xml file used a CertAuthenticator you need to manually

NULL for unrecognized certs, or for all certs, if certs

7. Enter

8. Click Apply to save your change.

9. Reboot the WebLogic Server.

X.509 in the Active Types box.

Cipher Suites

If you have trouble with your Certicom cipher suite, see the information about issue 073360 in the Release Notes.

1-14 BEA WebLogic Server 7.0 Upgrade Guide

Upgrading WebLogic Tuxedo Connector

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

 “Start the WebLogic Tuxedo Connector” on page 1-15

 “Convert WebLogic Tuxedo Connector XML Configuration Files” on page 1-16

 “Update Inbound RMI-IIOP Applications” on page 1-17

 “Authenticate Remote Users” on page 1-19

 “Set WebLogic Tuxedo Connector Properties” on page 1-20

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 at http://e-docs.bea.com/wls/docs70/wtc_admin/Install.html#WTCuseCLI.

Previous releases of the connector used 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 7.0, WebLogic Tuxedo Connector does not use a Startup or a Shutdown class. WebLogic Tuxedo Connector sessions are managed using a WTCServer MBean.

 You start a WebLogic Tuxedo Connector session when you assign a configured

WTCServer MBean to a selected server.

 You end a WebLogic Tuxedo Connector session by removing a WTCServer

MBean from WebLogic Server or when you shut down WebLogic Server.

For more information on starting and ending a WebLogic Tuxedo Connector session, see Assign a WTCServer to a Server at

http://e-docs.bea.com/wls/docs70/ConsoleHelp/wtc.html#AssignWTCServer.

BEA WebLogic Server 7.0 Upgrade Guide 1-15

1 Upgrading WebLogic Server 6.x to Version 7.0

Convert WebLogic Tuxedo Connector XML Configuration Files

WebLogic Tuxedo Connector is implemented as a service and no longer utilizes a separate XML configuration file. The configuration file information into the server. Use the following steps to convert your 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.

WTCMigrateCF tool migrates XML

config.xml file of an active Administration

4. Start the

java -Dweblogic.wtc.migrateDebug weblogic.wtc.gwt.WTCMigrateCF

-url URL -username USERNAME -password PASSWORD -infile CONFIGWTC

[-server SERVERNAME] [-domain DOMAIN] [-protocol PROTOCOL] [-deploy]

WTCMigrateCF tool. Enter the following command:

The arguments for this command are defined as follows:

Argument Description

-Dweblogic.wtc. migrateDebug

URL

USERNAME

PASSWORD

WebLogic property used to turn on wtc.migrateDebug mode.

URL passed to your server. Example:

User Name passed to your server. Example:

Password passed to your server. Example:

\\myServer:7001

system

mypasswd

1-16 BEA WebLogic Server 7.0 Upgrade Guide

Argument Description

Upgrading WebLogic Tuxedo Connector

CONFIGWTC

SERVERNAME

DOMAIN

PROTOCOL

-deploy

Fully qualified path and name of the WebLogic Tuxedo Connector XML configuration file to migrate to the config.xml file.

Example:

d:\bea\weblogic700\server\samples\examples\wtc \atmi\simpapp\bdmconfig.xml

Optional. The name of the administration or managed server that you want the new current active administration server.

Optional. The name of the WebLogic Server domain that you want the new WTCServer MBean assigned to. Default: the current active domain.

Optional. The protocol to use with URL. Default: t3:

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.

WTCServer MBean assigned to. Default: the

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 to a WTCServer Mbean and placed in the

config.xml file of the server specified in step 2.

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-IIOP at

http://bernal/stage/docs70/wtc_atmi/CORBA.html.

If you use inbound RMI-IIOP, 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

BEA WebLogic Server 7.0 Upgrade Guide 1-17

DOMAINID.

1 Upgrading WebLogic Server 6.x to Version 7.0

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

ior.txt file.

Example:

corbaloc:tgiop:servername/NameService

where servername is your server name

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

cnsbind -o ior.txt your_bind_name

where

your_bind_name is the object name from your Tuxedo application.

3. Modify the

*DM_REMOTE_SERVICES section of your Tuxedo domain

configuration file. Replace your WebLogic Server service name, formerly the

DOMAINID, with the name of your WebLogic Server.

Listing 1-1 Domain Configuration File

*DM_RESOURCES

VERSION=U22

*DM_LOCAL_DOMAINS

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

*DM_REMOTE_DOMAINS

TDOM2 TYPE=TDOMAIN DOMAINID="TDOM2"

*DM_TDOMAIN

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

*DM_REMOTE_SERVICES "//servername"

where servername is the name of your WebLogic Server.

1-18 BEA WebLogic Server 7.0 Upgrade Guide

+ 116 hidden pages

BEA WebLogic Server 7 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

About This Document

1. Upgrading WebLogic Server 6.x to Version 7.0

2. Upgrading WebLogic Server 4.5 and 5.1 to Version 7.0

A. The weblogic.properties Mapping Table

B. Upgrading the Pet Store Application and the Examples Server

About This Document

Audience

e-docs Web Site

How to Print the Document

Contact Us!

Documentation Conventions

Upgrading Your WebLogic Server Configuration: Main Steps

Modifying Startup Scripts

Understanding the WebLogic Server 7.0 Directory Structure

Porting an Application from WebLogic Server 6.x to WebLogic Server 7.0

Upgrading Security

Booting WebLogic Server in Compatibility Security

ACLs on MBeans

Upgrading from Compatibility Security to WebLogic Server 7.0 Security

Security Realms

Guest User

password.ini File

Upgrading the SSL Protocol

Creating a Trusted CA Keystore

Using CertAuthenticator in Compatibility Security

Cipher Suites

Upgrading WebLogic Tuxedo Connector

Start the WebLogic Tuxedo Connector

Convert WebLogic Tuxedo Connector XML Configuration Files

Update Inbound RMI-IIOP Applications