Skip navigation.
Downloads | Product Documentation | Support

Configuring and Managing WebLogic Server

# Overview of WebLogic Server Domains

The following sections describe WebLogic Server domains:

- What Is a Domain?
- Contents of a Domain
- Administration Server
- Creating a New Domain
- Managed Servers and Clustered Managed Servers
- Resources and Services
- Common Domain Types
- Domain Restrictions
- Directory Structure

# What Is a Domain?

A domain is the basic administration unit for WebLogic Server instances. A domain consists of one or more WebLogic Server instances (and their associated resources) that you manage with a single Administration Server. You can define multiple domains based on different system administrators' responsibilities, application boundaries, or geographical locations of servers. Conversely, you can use a single domain to centralize all WebLogic Server administration activities.

Each domain's configuration is stored in a separate configuration file called `config.xml`, which is stored on the Administration Server along with other files such as logs and security files. When you use the Administration Server to perform a configuration task, the changes you make apply only to the domain managed by that Administration Server. To manage another domain, use the Administration Server for that domain. For this reason, the servers instances, applications, and resources in one domain should be treated as being independent of servers, applications, and resources in a different domain.You cannot perform configuration or deployment tasks in multiple domains at the same time.

For more information, see

- Starting and Stopping Servers in the Administration Console Online Help
- Starting the Administration Console

## Contents of a Domain

A domain can include multiple WebLogic Server clusters and non-clustered WebLogic Server instances. A minimal domain can contain only one WebLogic Server instance, which functions both as an Administration Server, and as a Managed server—such a domain can be useful while developing applications, but is not recommended for use in a production environment. Although the scope and purpose of a domain can vary significantly, most WebLogic Server domains contain the components described in this section.

Figure 2-1 shows a production environment that contains an Administration Server, three standalone Managed Servers, and a cluster of three Managed Servers.

Figure 2-1 WebLogic Server Domain

## Production and Development Modes

You can configure servers in your domain to start in one of two modes, development or production. You use development mode while you are developing your applications. Development mode uses a relaxed security configuration and enables you to auto-deploy applications. You use production mode when your application is running in its final form. A production domain uses full security and may use clusters or other advanced features. For more information on the differences between development mode and production mode, refer to "Differences Between Configuration Startup Modes."

The runtime mode is a domain-wide setting. As each Managed Server starts, it refers to the mode of the Administration Server to determine its runtime mode. By default, all servers run in development mode. If you configure the domain to run in production mode, the Administration Server saves this setting to the domain's `config.xml` file.

BEA recommends that you set the mode when you first create a domain. For information on creating a domain that runs in production mode, see Example: Creating a Domain with Administration Server and Clustered Managed Servers.

It is possible, but not recommended, to change the mode of an existing domain. See Changing the Runtime Mode in Administration Console Online Help.

# Creating a New Domain

This section discusses several ways to create a new domain. For information about restrictions for creating and using domains, see Domain Restrictions.

## Server Name Considerations

Each server instance in your WebLogic environment must have a unique name, regardless of the domain or cluster in which it resides, or whether it is an Administration Server or a Managed Server. Within a domain, each server, machine, cluster, virtual host, and any other resource type must be named uniquely and must not use the same name as the domain.

For WebLogic JMS, this strict unique naming rule also applies to JMS resources, such as JMS servers and stores in multi-domain environments when using the WebLogic Messaging Bridge or the Foreign JMS Server feature for intra-domain operability. For additional naming requirements, see "JMS Resource Naming Rules for Domain Interoperability" in the Administration Console Online Help.

JTA transactions are also subject to strict unique naming rules for inter-domain transactions. For more information see "Configuring Domains for Inter-Domain Transactions" in the Administration Console Online Help.

## Creating a Domain Using the Configuration Wizard

The Configuration Wizard is the easiest and recommended way to create a new WebLogic Server domain. The configuration Wizard interactively queries you about the type of domain you want to create and creates the `config.xml` file, start scripts, and other files used in a domain. Using the Configuration Wizard you can:

- Create a domain with a single WebLogic Server instance for use in a development environment
- Create a domain with one or more Managed Servers
- Create a domain with one or more clusters
- Configure JDBC connection pools, DataSources, and MultiPools
- Configure JMS
- Add users to the security realm
- Create a domain based on a configuration template. A configuration template defines the full set of resources within a domain, including infrastructure components, applications, services, security options, and general environment and operating system options. You can use one of the provided configuration templates or create your own template. See Configuration Template Builder.

For more information, see :

- Creating and Configuring Domains Using the Configuration Wizard.
- Configuring WebLogic Platform

## Creating a Domain Using the weblogic.Server Command

If you start a WebLogic Server instance from a directory that does not contain a `config.xml` file, the server automatically creates a default configuration, including start scripts and the `config.xml` file, in the directory from which you start the server instance. You can then modify the domain configuration using the Administration Console or other system administration tools.

To create a domain using the `weblogic.Server` command:

1. Open a command shell.
2. Set the `CLASSPATH` to include the WebLogic Server classes. The easiest way to set your `CLASSPATH` is to run the `setWLSEnv.cmd` (Windows) or the `setWLSEnv.sh` (UNIX) script. The script is located in the WebLogic Server installation at:

`BEA_Home/weblogic81/server/bin`

3. Run the following command:

`java weblogic.Server`

When you are prompted for a username and password, enter any values you choose. You will be prompted with:

`Would you like the server to create a default configuration and boot? (y/n)`

Note: If you want to specify a name for your domain add the `-Dweblogic.Domain` option to the start command. For example, the command

`java -Dweblogic.Domain=Chicago weblogic.Server`

creates a domain called "Chicago".

4. Answer `Y.` You will be asked to confirm the password.
5. Enter the same password you entered in step 3. The server starts and creates a default `config.xml` file in the directory from which you ran the `java weblogic.Server` command.

The server creates a Boot Identity file (called `boot.properties`) that contains the username and password you entered in step 3. When this file is present in the domain's root directory, the server does not prompt for a username and password during startup.

## Creating a Domain Using Ant Tasks

You can create a new domain configuration using Ant scripts by running the `wlserver` and `wlconfig` Ant tasks. For more information, see Using Ant Tasks to Configure a WebLogic Server Domain in the WebLogic Server Command Reference.

# Administration Server

Each WebLogic Server domain must have one server instance that acts as the Administration Server. You use the Administration Server—programmatically, via the Administration Console, or using the command line—to configure all other server instances and resources in the domain.

## Role of the Administration Server

Before you start the Managed Servers in a domain, start the Administration Server. When you start a standalone or clustered Managed Server, it contacts the Administration Server for its configuration information. In this way, the Administration Server operates as the central control entity for the configuration of the entire domain.

You can invoke the services of the Administration Server in the following ways:

- WebLogic Server Administration Console—The Administration Console is a browser-based graphical user interface (GUI) you use to configure a domain. For more information, see Using the Administration Console in Administration Console Online Help.
- WebLogic Server Application Programming Interface (API)—You can write a Java class to modify configuration attributes using the API provided with WebLogic Server. For more information, see Programming WebLogic Management Services with JMX.
- WebLogic Server command-line utility—This utility (`weblogic.Admin`) allows you to create scripts to automate domain management. For more information, see WebLogic Server Command Reference.
- SNMP—You can use Simple Network Management Protocol, versions SNMPv1 and SNMPv2 to monitor a WebLogic Server domain. For more information, see WebLogic SNMP Management Guide.

Whichever method is used, the Administration Server for a domain must be running to modify the domain configuration.

When the Administration Server starts, it loads the `config.xml` for the domain. It looks for `config.xml` in the current directory. When you create a new domain using the Configuration Wizard, you can specify the domain location, or by default the domain is placed at:

`BEA_HOME/user_projects/domains/``mydomain`

where `mydomain` is a domain-specific directory, with the same name as the domain.

Each time the Administration Server starts successfully, and each time you modify the configuration, a backup configuration file is created. You can configure the number of backup copies of `config.xml` retained by the Administration Server. For more information, see Backing up config.xml.

## What Happens If the Administration Server Fails?

The failure of an Administration Server for a domain does not affect the operation of Managed Servers in the domain. If an Administration Server for a domain becomes unavailable while the server instances it manages—clustered or otherwise—are up and running, those Managed Servers continue to run. If the domain contains clustered server instances, the load balancing and failover capabilities supported by the domain configuration remain available, even if the Administration Server fails.

If an Administration Server fails because of a hardware or software failure on its host machine, other server instances on the same machine may be similarly affected. However, the failure of an Administration Server itself does not interrupt the operation of Managed Servers in the domain.

For more information, see Recovering Failed Servers.

# Managed Servers and Clustered Managed Servers

In a domain, server instances other than the Administration Server are referred to as Managed Servers. Managed Servers host the components and associated resources that constitute your applications—for example, JSPs and EJBs. When a Managed Server starts up, it connects to the domain's Administration Server to obtain configuration and deployment settings.

Note: Managed Servers in a domain can start up independently of the Administration Server if the Administration Server is unavailable. See Recovering Failed Servers for more information.

Two or more Managed Servers can be configured as a WebLogic Server cluster to increase application scalability and availability. In a WebLogic Server cluster, most resources and services are deployed to each Managed Server (as opposed to a single Managed Server,) enabling failover and load balancing. To learn which component types and services can be clustered, see What Types of Objects Can Be Clustered? in Using WebLogic Server Clusters.

You create a non-clustered Managed Server and add it to a cluster by configuring pertinent configuration parameters for the server instance and the cluster using the Administration Console or other system administration tools. Conversely, you can remove a Managed Server from a cluster by re-configuring the parameters appropriately. The key difference between clustered and non-clustered Managed Servers is support for failover and load balancing—these features are available only in a cluster of Managed Servers.

Your requirements for scalability and reliability drive the decision on whether or not to cluster Managed Servers. For example, if your application is not subject to variable loads, and potential interruptions in application service are acceptable, clustering may be unnecessary.

For more information about the benefits and capabilities of a WebLogic Server cluster, see Introduction to WebLogic Server Clustering in Using WebLogic Server Clusters. A single domain can contain multiple WebLogic Server clusters, as well as Managed Servers that are not configured as clusters.

# Resources and Services

In addition to the Administration Server and Managed Servers, a domain also contains the resources and services required by Managed Servers and hosted applications deployed in the domain.

Examples of domain-level resources include:

- Machine definition to identify a specific computer. A Machine definition is used to associate a computer with the Managed Server(s) it hosts. This information is used by Node Manager in restarting a failed Managed Server, and by a clustered Managed Server in selecting the best location for storing replicated session data. For more information about Node Manager, see Overview of Node Manager.
- Network channels, an optional resource that can be used to define default ports, protocols, and protocol settings. After creating a network channel, you can assign it to any number of Managed Servers and clusters in the domain. See Configuring Network Resources for more information.

Managed Servers in the domain host their own resources and services. You can deploy resources and services to selected Managed Servers or to a cluster. Examples of deployable resources include:

- Application components, such as EJBs, Web Applications, J2EE Connectors and Enterprise Applications
- Startup and shutdown classes
- JDBC connection pools
- JMS servers
- Virtual Hosts

# Common Domain Types

There are two basic types of domains:

- Domain with Managed Servers: A simple production environment can consist of a domain with several Managed Servers that host applications, and an Administration Server to perform management operations. In this configuration, applications and resources are deployed to individual Managed Servers; similarly, clients that access the application connect to an individual Managed Server.

Production environments that require increased application performance, throughput, or availability may configure two or more of Managed Servers as a cluster. Clustering allows multiple Managed Servers to operate as a single unit to host applications and resources. For more information about the difference between a standalone and clustered Managed Servers, see Managed Servers and Clustered Managed Servers.

- Standalone Server Domain: For development or test environments, you may want to deploy a single application and server independently from servers in a production domain. In this case, you can deploy a simple domain consisting of a single server instance that acts as an Administration Server and also hosts the applications you are developing. The examples domain that you can install with WebLogic Server is an example of a standalone server domain.

Note: In production environments, deploy applications only on Managed Servers in the domain. The Administration Server should be reserved for management tasks. For more information, see Creating and Configuring Domains Using the Configuration Wizard.

# Domain Restrictions

Many WebLogic Server installations consist of a single domain that includes all the Managed Servers required to host applications. Note the following restrictions for domains:

- Do not create a domain named "weblogic". This name is reserved for internal use by WebLogic Server.
- If you create more than one domain:

- Each domain requires its own Administration Server for performing management activities. To manage another domain, start the Administration Console hosted by the Administration Server of that domain, or use the URL of the Administration Server in the command line arguments.
- All Managed Servers in a cluster must reside in the same domain; you cannot "split" a cluster over multiple domains.
- You cannot share a configured resource or subsystem between domains. For example, if you create a JDBC connection pool in one domain, you cannot use it with a Managed Server or cluster in another domain. (Instead, you must create a similar connection pool in the second domain.)

- Each server instance in your WebLogic environment must have a unique name, regardless of the domain or cluster in which it resides, or whether it is an Administration Server or a Managed Server. Within a domain, each server, machine, cluster, virtual host, and any other resource type must be named uniquely and must not use the same name as the domain. For more information see, Server Name Considerations.

# Directory Structure

This section discusses the directory structure for a domain and for server instances in a domain.

## The config.xml file

The configuration of a domain is stored in the `config.xml` file for the domain. (You can specify another name for this file by specifying a command line option when you start the Administration server.) The `config.xml` file specifies the name of the domain and the configuration parameter settings for each server instance, cluster, resource, and service in the domain. The `config.xml` file must exist in the Server Root Directory of the Administration Server. (See Server Root Directory for an Administration Server.)

This directory also contains default script files that you can use to start the Administration Server and Managed Servers in the domain. For more information about these scripts and other methods of starting a server instance, see Starting and Stopping WebLogic Server in the Administration Console Online Help.

## Domain Directory Structure

In releases of WebLogic Server prior to version 7.0, domain directories were created within the directory structure of the Weblogic Server installation. With WebLogic Server 8.1, you can set up domain directories outside the product installation directory tree, in any location on the file system that has access to the Weblogic Server installation and the JDK.

When you use the Configuration Wizard to create a domain, by default it creates the `user_projects/domains` directory in the BEA Home directory as a container for your domains (you can also specify a different directory anywhere on the file system). It also creates a root directory for the new domain and any other directories specified in the domain template that you select to create the domain.

The domain directory structure created by the Configuration Wizard contains:

- A domain root directory with the same name as the domain, such as `mydomain` or `petstore`. This directory contains the following:

- The `config.xml` file for the domain
- Scripts you use to start server instances and establish your environment
- A subdirectory for storing applications for the domain, typically named `applications`.

Note: If you plan to use the WebLogic Server's auto-deployment feature—available only when a domain is running in development mode—the subdirectory for applications must be named `applications`. For information about auto-deployment, see Auto-Deployment in Developing WebLogic Server Applications.

When you start a server instance in a domain for the first time, Weblogic Server creates the following subdirectories in the domain directory:

- Files containing security information.
- A`logs` directory for storing domain-level logs.
- A directory for each server running in the domain, for storing server logs and HTTP access logs. For more information, see A Server's Root Directory.

You can create other directories within the domain directory structure, as desired.

## A Server's Root Directory

All instances of WebLogic Server use a server root directory to store runtime data and to provide the context for any relative pathnames in the server's configuration. When you start a WebLogic Server instance for the first time, a subdirectory is created for each server instance under the server root directory. These subdirectories contain log files, security data, administrative data, and other files used by the server instance.

You can specify the path and name of the server root directory for each server instance. You can specify a common server root directory for multiple server instances hosted on a single computer or you can specify a different server root directory for each server. A domain may have one or more server root directories.

The server root directory may also contain a subdirectory called `applications` that is used for auto-deployment of applications when a domain is running in development mode.

For example, in Figure 2-2, the server root directory is called `MyServerRootDirectory.` WebLogic Server instances named `server-1` and `server-2` each have their own subdirectory under the server root directory. The name of these subdirectories is the name of the server as defined in the domain's configuration.

Figure 2-2 Server Root Directory

### Specifying a Server Root Directory

You can specify the path for the server root directory by one of the following means:

- Use the `-Dweblogic.RootDirectory=``path` option when starting a WebLogic Server instance from command line. For example the following command:

>     java -Dweblogic.RootDirectory=c:\MyServerRootDirectory weblogic.Server

starts a WebLogic Server instance and uses `c:\MyServerRootDirectory` as the server root directory.

- If you use Node Manager to start a WebLogic Server instance, you can specify a server root directory with the Root Directory attribute in the Administration Console on the Server --> Configuration --> Remote Start tab.

If you do not use one of the above means to specify a server root directory, the path and name of the server root directory depend on whether a server instance is a Managed Server or the Administration Server and whether or not you use Node Manager to start the server instance. These variations are discussed in the next sections.

### Server Root Directory for an Administration Server

An Administration Server uses its server root directory as a repository for the domain's configuration data (such as `config.xml`) and security resources (such as the default, embedded LDAP server).

To determine the root directory for an Administration Server, WebLogic Server does the following:

- If the server's startup command includes the `-Dweblogic.RootDirectory=``path` option, then the value of `path` is the server root directory.
- If `-Dweblogic.RootDirectory=``path` is not specified, and if the working directory (that is, the directory from which you issue the startup command) contains a `config.xml` file, then the working directory is the server root directory.
- If neither of the previous statements is true, then the server looks for a `config.xml` file in `working-directory``/config/``domain-name`. If it finds `config.xml` in this directory, then `working-directory``/config/``domain-name` is the server root directory.
- If WebLogic Server cannot find a `config.xml` file, then it offers to create one. You can use this method to create a new domain. For more information, see Using the weblogic.Server Command Line to Create a Domain in the WebLogic Server Command Reference.

### Server Root Directory for a Managed Server Started with Node Manager

If you use the Node Manager to start a Managed Server, the root directory is located on the computer that hosts the Node Manager process. To determine the location of the server's root directory, WebLogic Server does the following:

- If you specified a root directory in the Administration Console on the Server --> Configuration --> Remote Start tab, then the directory you specified is the server root directory.
- If you did not specify a root directory in the Administration Console, then the server root directory is:
  `BEA_HOME``\``WL_HOME``\common\nodemanager
  `where:

- `BEA_HOME` is the directory where you installed one or BEA products, including WebLogic Server
- `WL_HOME` is the directory in which you installed WebLogic Server on the Node Manager's host computer (`weblogic81` by default)

The server root directory for a Managed Server started with Node Manager directory contains a subdirectory for each Managed Server instance. The name of the subdirectory is the name of the server as defined in the domain configuration.

### Server Root Directory for a Managed Server Not Started with Node Manager

If you do not use the Node Manager to start a Managed Server (and therefore use the `java weblogic.Server` command or a script that calls that command), WebLogic Server does the following to determine the root directory:

- If the server's startup command includes the `-Dweblogic.RootDirectory=``path` option, then the value of `path` is the server's root directory.
- If `-Dweblogic.RootDirectory=``path` is not specified, then the working (current) directory is the root directory. For example, if you run the `weblogic.Server` command from `c:\config\MyManagedServer`, then `c:\config\MyManagedServer` is the root directory.

Note: To make it easier to maintain your domain configurations and applications across upgrades of WebLogic Server software, it is recommended that the sever root directory not be the same as the installation directory for the WebLogic Server software.