WebLogic Server Partners' Guide

Customizing WebLogic Server Configuration Files

WebLogic Server stores configuration information, such as security credentials and the list of deployable resources and applications, in a set of configuration files.

The following sections highlight typical modifications that partners and ISVs make to the WebLogic Server configuration files that they distribute with their applications:

Customizing the config.xml File

The config.xml file defines the majority of configuration settings for all WebLogic Servers in a management domain. For example, config.xml controls all details of a given domain, including the name, number and configuration of servers and cluster; the list of deployable resources and applications; and the mapping of deployable resources and applications to servers and clusters.

Usually, BEA recommends that you use such WebLogic Server tools as the Administration Console, the weblogic.Admin utility, or the Configuration Wizard to modify the config.xml file. Partners, however, may need to edit this file directly in order to customize an installation.

The following sections highlight elements of the config.xml file that partners might modify for their installations:

If you are unfamiliar with the role of the config.xml file or management domains, refer to the following:

"Directory Structure" in Configuring and Managing WebLogic Server
"Understanding Cluster Configuration and Application Deployment" in Using WebLogic Server Clusters

If you are unfamiliar with editing config.xml directly, see the WebLogic Server Configuration Reference, which provides conventions for editing config.xml.

Pre-Configuring WebLogic Server Resources

Partner applications typically rely on several WebLogic Server resources, each of which is defined in the config.xml file. Table 2-1 provides an overview of the config.xml elements that partners typically use to pre-configure WebLogic Server resources.

Table 2-1 WebLogic Server Resource Definitions in the config.xml File

Resources	config.xml Elements	Notes
Domain	Domain	To act as a cohesive unit, all WebLogic Servers that host a component of your application must reside within a single WebLogic Server administrative domain.
Server Names and Connection Information	Server	Partner applications can be configured to access one or more WebLogic Server names, IP addresses, and/or port numbers, or, if necessary for your application, you can hard-code a WebLogic Server domain to use specific server names and connection ports. IP Addresses can be configured dynamically by the application installer and embedded into a `config.xml` before installing the configuration.
JDBC Datasources	JDBCConnectionPool JDBCDataSource JDBCMultiPool JDBCTxDataSource	Partner applications that install WebLogic Server also frequently install an RDBMS or other datastore for maintaining the application data. If your product installer installs a datastore along with the application, you may want to pre-configure the installed WebLogic Server to set up a default datasource and connection pool for the datastore.

Resources

config.xml Elements

Notes

Domain

To act as a cohesive unit, all WebLogic Servers that host a component of your application must reside within a single WebLogic Server administrative domain.

Server Names and Connection Information

Server

Partner applications can be configured to access one or more WebLogic Server names, IP addresses, and/or port numbers, or, if necessary for your application, you can hard-code a WebLogic Server domain to use specific server names and connection ports.

IP Addresses can be configured dynamically by the application installer and embedded into a config.xml before installing the configuration.

JDBC Datasources

Partner applications that install WebLogic Server also frequently install an RDBMS or other datastore for maintaining the application data. If your product installer installs a datastore along with the application, you may want to pre-configure the installed WebLogic Server to set up a default datasource and connection pool for the datastore.

Deployment of Application Components

Partner applications can also be installed by adding the necessary elements to config.xml. Installing an application into a pre-configured WebLogic Server, however, requires coordination between the config.xml settings and the installed location of application component files (.war, .jar, .html and so forth).

Table 2-2 provides an overview of elements used to pre-deploy application components within WebLogic Server. See Example Configuration for an example of how these elements correspond to the installed location of actual application component files.

Table 2-2 Application Component Definitions in the config.xml File

Components	config.xml Elements	Notes
Startup Classes	StartupClass	WebLogic Server startup classes can be used to initialize resources required by other components of the partner application.
Webserver	WebServer	Web applications typically require standard web resources, such as static `.html` content, in addition to business logic. Use the `config.xml` file to configure the default location of these static files for the application.
Web Applications	Application	EAR and WAR files can be stored anywhere in your application directory or the WebLogic Server directory. Reference the final installed location from within config.xml to deploy the application on startup.

Example Configuration

When you install WebLogic Server, by default you also install the Avitek Medical Records sample domain. This sample domain includes a server configuration that defines resources for database connectivity and messaging. The domain also contains a enterprise applications that include EJBs and Web applications.

The following sections highlight key aspects of the config.xml file that configures the Avitek Medical Records domain. The file is located in the root directory of the domain's Administration Server: WL_HOME\samples\domains\medrec\config.xml
where WL_HOME is the directory in which you installed WebLogic Server:

Domain Configuration

The parent element in the config.xml file, <Domain>, provides the configuration for the medrec domain. All of the application's servers, resources, and components are defined within this element.

Listing 2-1 Parent Element

<Domain
   Name="medrec"
   ConfigurationVersion="8.1.0.0"
>

Database Connections

The Avitek Medical Records domain defines two JDBC connection pools and one transactional data source. Each connection pool connects to a different type of database.

The elements in the config.xml file include information on how to connect to the database, definitions for the database driver, credentials for logging in to the database, and capacity properties of the connection pool.

Each JDBCConnectionPool element also lists the server instances to which it has been targeted. The connection pools are a domain-wide resource: they can be targeted to any server in the domain and used by any application that is deployed on one of those servers.

Listing 2-2 Elements that Configure Database Connections

<!-- PointBase -->
<JDBCConnectionPool
    CapacityIncrement="1"
    DriverName="com.pointbase.jdbc.jdbcUniversalDriver"
    InitialCapacity="1"
    MaxCapacity="10"
    Name="MedRecPool-PointBase"
    Password="MedRec"
    Properties="user=MedRec"
    RefreshMinutes="0"
    ShrinkPeriodMinutes="15"
    ShrinkingEnabled="true"
    Targets="MedRecServer"
    TestConnectionsOnRelease="false"
    TestConnectionsOnReserve="false"
    URL="jdbc:pointbase:server://localhost/demo"
/>

<!-- Oracle -->
<JDBCConnectionPool
    CapacityIncrement="2"
    DriverName="oracle.jdbc.driver.OracleDriver"
    InitialCapacity="4"
    LoginDelaySeconds="1"
    MaxCapacity="10"
    Name="MedRecPool-Oracle"
    Password="tiger"
    Properties="user=scott"
    RefreshMinutes="10"
    ShrinkPeriodMinutes="15"
    ShrinkingEnabled="true"
    Targets=""
    TestConnectionsOnRelease="false"
    TestTableName="dual"
     URL="jdbc:oracle:thin:@my-oracle-server:my-oracle-server-port:my-oracle-sid"
/>

<JDBCTxDataSource
    JNDIName="MedRecTxDataSource"
    Name="MedRecTxDataSource"
    PoolName="MedRecPool-PointBase"
    Targets="MedRecServer"
    EnableTwoPhaseCommit="true"
    />

Messaging Resources

The Avitek Medical Records domain contains JMS messaging resources for distributing messages between the applications in the domain.

Note that one of the JMSJDBCStore elements is surrounded by comment tags <! -->. Because it is surrounded by comment tags, the element is invisible to the Administration Console and other utilities that manage WebLogic Server. In addition, the Administration Server ignores the element and therefore the JDBC store that the element describes is unavailable to the domain.

The comment tags were added by editing the config.xml file in a text editor. BEA utilities such as the Administration Console do not use comment tags to hide or disable resources. To make the JDBC store available to the domain:

Stop the Administration Server.

Open the config.xml file in a text editor and remove the comment tags.

Restart the Administration Server.

Listing 2-3 Elements for Configuring JMS Resources

<JMSJDBCStore
    ConnectionPool="MedRecPool-PointBase"
    Name="MedRecJMSJDBCStore"
    PrefixName="MedRec"
/>

<!-- For Oracle user Scott
<JMSJDBCStore
    ConnectionPool="MedRecPool-Oracle"
    Name="MedRecJMSJDBCStore"
    PrefixName="Scott"
/>
-->

<JMSServer
    Name="MedRecJMSServer"
    Store="MedRecJMSJDBCStore"
    Targets="MedRecServer"
>

    <JMSQueue
        JNDIName="jms/REGISTRATION_MDB_QUEUE"
        Name="jms/REGISTRATION_MDB_QUEUE"/>

     <JMSQueue
        JNDIName="jms/MAIL_MDB_QUEUE"
        Name="jms/MAIL_MDB_QUEUE"/>

     <JMSQueue
        JNDIName="jms/XML_UPLOAD_MDB_QUEUE"
        Name="jms/XML_UPLOAD_MDB_QUEUE"/>

</JMSServer>

Application Components

The Avitek Medical Records domain includes three enterprise applications: medrecEar, physicianEar, opc.ear, and startupEar. The physicianEar enterprise application includes Web applications and EJBs. On Windows, the element in Listing 2-4 configures the physicianEar application.

Note that the c:/bea/wlserver810 portion of the application component path is determined during the WebLogic Server installation, while the remaining portion of the path is hard-coded. Your application installer can use a similar technique to install application components in a subdirectory unrelated to WebLogic Server, if necessary.

Listing 2-4 Elements for Configuring Applications

<!--   MedRec Enterprise Applications   -->
<Application
    Name="MedRecEAR"
    Deployed="true"
    Path="c:/bea/wlserver810/samples/server/medrec/build/medrecEar"
    StagingMode="nostage"
    TwoPhase="true"
    LoadOrder="1">

    <WebAppComponent Name="AdminWAR" Targets="MedRecServer" URI="adminWebApp"/>
    <WebAppComponent Name="MainWAR" Targets="MedRecServer" URI="mainWebApp"/>
    <WebAppComponent Name="PatientWAR" Targets="MedRecServer"
          URI="patientWebApp"/>
    <EJBComponent Name="EntityEJB" Targets="MedRecServer" URI="entityEjbs"/>
    <EJBComponent Name="MdbEJB" Targets="MedRecServer" URI="mdbEjbs"/>
    <EJBComponent Name="SessionEJB" Targets="MedRecServer" URI="sessionEjbs"/>
    <EJBComponent Name="WebServicesEJB" Targets="MedRecServer"
         URI="webServicesEjb"/>
    <WebServiceComponent Name="WebServicesWAR" Targets="MedRecServer"
         URI="ws_medrec"/>
</Application>

Basic Server Setup

The Avitek Medical Records domain uses a single server named MedRecServer. The Server element configures the server's listen port, communication protocols, Java compiler, and other attributes.

Listing 2-5 Elements for Server Configuration

<!-- WebLogic Server Configuration -->

  <Server
     JavaCompiler="javac"
     ListenPort="7001"
     Name="MedRecServer"
     IIOPEnabled="false"
     InstrumentStackTraceEnabled="false">

     <ExecuteQueue
       Name="default"
       ThreadCount="15"
     />

     <SSL
       Name="MedRecServer"
       Enabled="true"
       ListenPort="7002"
     />

</Server>

Security Realm

All WebLogic Server domains must configure a default security realm, which determines who can access resources within the domain. The elements in Listing 2-6 configure the default security realm for the Avitek Medical Records domain.

Elements such as <weblogic.security.providers.authentication.DefaultAuthenticator> specify an MBean that manages a Security Provider. For example, the aforementioned element configures the realm to use the Authenticator Provider that is managed by an MBean named Security:Name=myrealmDefaultAuthenticator"Realm="Security:Name=myrealm. This element also configures the realm to treat this Authenticator Provider as SUFFICIENT for authenticating users.

The last elements in Listing 2-6 configure compatibility security, which enables the domain to use security configurations from WebLogic Server 6.x. For more information, refer to Customizing Files for Compatibility Security.

Listing 2-6 Elements for Configuring the Security Realm

<!-- Security -->
<Security
    Name="medrec"
    PasswordPolicy="wl_default_password_policy"
    Realm="wl_default_realm"
    RealmSetup="true">

    <weblogic.security.providers.authentication.DefaultAuthenticator
        ControlFlag="SUFFICIENT"
        Name="Security:Name=myrealmDefaultAuthenticator"
                      Realm="Security:Name=myrealm"/>
    <weblogic.security.providers.authentication.DefaultIdentityAsserter
        ActiveTypes="AuthenticatedUser"
        Name="Security:Name=myrealmDefaultIdentityAsserter"
                      Realm="Security:Name=myrealm"/>
    <weblogic.security.providers.authorization.DefaultRoleMapper
        Name="Security:Name=myrealmDefaultRoleMapper"
                       Realm="Security:Name=myrealm"/>
    <weblogic.security.providers.authorization.DefaultAuthorizer
        Name="Security:Name=myrealmDefaultAuthorizer"
                       Realm="Security:Name=myrealm"/>
    <weblogic.security.providers.authorization.DefaultAdjudicator
        Name="Security:Name=myrealmDefaultAdjudicator"
                       Realm="Security:Name=myrealm"/>
    <weblogic.security.providers.credentials.DefaultCredentialMapper
        Name="Security:Name=myrealmDefaultCredentialMapper"
                       Realm="Security:Name=myrealm"/>
        <weblogic.management.security.authentication.UserLockoutManager
        Name="Security:Name=myrealmUserLockoutManager"
                       Realm="Security:Name=myrealm"/>

    <weblogic.management.security.Realm
        Adjudicator="Security:Name=myrealmDefaultAdjudicator"
        AuthenticationProviders="Security:Name=myrealmDefaultAuthenticator|
                        Security:Name=myrealmMedRecSampleAuthenticator|
                        Security:Name=myrealmDefaultIdentityAsserter"
        Authorizers="Security:Name=myrealmDefaultAuthorizer"
        CredentialMappers="Security:Name=myrealmDefaultCredentialMapper"
        DefaultRealm="true"
        DeployPolicyIgnored="false"
        DeployRoleIgnored="false"
        DisplayName="myrealm"
        FullyDelegateAuthorization="true"
        Name="Security:Name=myrealm"
        RoleMappers="Security:Name=myrealmDefaultRoleMapper"
        UserLockoutManager="Security:Name=myrealmUserLockoutManager"/>

    <com.bea.medrec.security.MedRecSampleAuthenticator
        ControlFlag="SUFFICIENT"
        Name="Security:Name=myrealmMedRecSampleAuthenticator"
                             Realm="Security:Name=myrealm"/>

</Security>

<PasswordPolicy Name="wl_default_password_policy"/>
<Realm FileRealm="wl_default_file_realm" Name="wl_default_realm"/>
<FileRealm Name="wl_default_file_realm"/>

Customizing Files for Compatibility Security

Compatibility security refers to the capability of running security configurations from WebLogic Server 6.x in WebLogic Server 8.1. If you run WebLogic Server with Compatibility security, your distribution must include the following:

A fileRealm.properties file, which defines the ACLs, groups, and security principles for the default WebLogic Server security realm
The following minimal set of elements in config.xml:

<Domain Name="mydomain"> <Security Name="mydomain" Realm="mysecurity"/> <Realm Name="mysecurity" FileRealm="myrealm"/> <FileRealm Name="myrealm"/> <Server ListenPort="7001" Name="myserver"> </Server> </Domain>

If your application requires integration with a third-party security realm (for example, single sign-on using the Windows NT security realm), you must also configure a caching realm.

For more information on WebLogic Server security, refer to the following topics:

Using Compatibility Security in the Managing WebLogic Security guide.
The Security page on the WebLogic Server documentation Web site.
The BEA WebLogic Server Configuration Reference, which provides conventions for editing config.xml.