Understanding Domain Configuration
WebLogic Server management and configuration services are accessed with the Java Management Extensions (JMX) API. The configuration of a domain is stored in XML files in the configuration directories under the domain directory. The files in these configuration directories act as a persistent store for the managed objects that WebLogic Server creates and modifies during its executing using the JMX API. The purpose of the configuration files is to store changes to managed configuration objects so that they are available when WebLogic Server is restarted.
The central configuration file for the domain is DOMAIN_NAME
config/config.xml file. It specifies the name of the domain and the configuration parameter settings for each server instance, cluster, resource, and service in the domain. The configuration for some major subsystems of the domain is stored in subdirectories of the DOMAIN_NAME
/config directory in separate configuration files that are incorporated by reference into the central
The domain directory also contains default script files, such as
startWebLogic.sh, that you can use to start the domain's Administration Server and Managed Servers. For details about these configuration files and script files, see Domain Directory Contents.
The central configuration file for the domain is the
/config/config.xml file. It specifies the name of the domain and the configuration parameter settings for each server instance, cluster, resource, and service in the domain.
config.xml file complies with an XML Schema whose URL is
http://www.bea.com/ns/weblogic/90/domain. This schema is also located in a JAR file in the file system at
BEA_HOME/weblogic90/server/lib/schema/weblogic-domain-binding.jar; the schema's pathname within the JAR file is
META-INF/schemas/schema-0.xsd. The XML Schema enables the use of XML editing tools to modify and validate the
For a reference guide to the domain configuration XML Schema, see the WebLogic Server Domain Configuration Schema Reference.
In most circumstances, you should not directly modify the
config.xml file or the other configuration files. Instead, use the Administration Console or one of the other tools described in Summary of System Administration Tools and APIs in Overview of WebLogic Server System Administration to modify the domain's configuration. The configuration changes will then be reflected in the configuration files.
Warning: You cannot edit configuration files while WebLogic Server is executing, since WebLogic Server rewrites the files periodically. Your changes will be lost and, depending on your platform, you could cause WebLogic Server failures.
Since the WebLogic Server configuration files are well-formed XML files, it is possible to modify them using XSLT or to script certain repetitive changes using an XML parser application such as Apache Xerces, or JDOM. Be sure to test any scripts you create thoroughly and always make a backup copy of each configuration file before you make any changes to it.
Security credentials for domain security and the embedded LDAP server are stored in the
config.xml file in encrypted form. If you create your
config.xml file by hand, you need to locate these credentials, encrypt them, and copy the encrypted credential into your
For information about WebLogic Server's encryption utility, see encrypt in the WebLogic Server Command Reference. Once you have encrypted the credentials, include the encrypted values in your
config.xml file in elements as in Listing 3-1:
In previous releases, the
config.xml file was a repository for all configuration information. In this release, several WebLogic Server subsystems are configured in subsidiary configuration files that are referred to by the central
config.xml file. These subsidiary configuration files reside in subdirectories of the
/config directory. For more information about these subsidiary configuration files, see Domain Directory Overview and Domain Directory Contents.
You can configure WebLogic Server to make backup copies of the configuration files. This facilitates recovery in cases where configuration changes need to be reversed or the unlikely case that configuration files become corrupted. When the Administration Server starts up, it saves a JAR file named
config-booted.jar that contains the configuration files. When you make changes to the configuration files, the old files are saved in the
configArchive directory under the domain directory, in a JAR file with a sequentially-numbered name like
Whether to back up configuration files is specified by the
DomainMBean.ConfigBackupEnabled attribute, whose default value is false. The number of configuration archive files retained is specified by the
DomainMBean.ArchiveConfigurationCount attribute, whose default value is 0.
WebLogic Server installs the domain directory by default within the
/user_projects/domains directory. Figure 3-1 is an overview of the domain directory tree hierarchy within the
domains directory. The
server-name directory names are not literal, but are replaced in any actual case with whatever specific names are appropriate; the other directory names are literal. This overview shows only directories, not files within the directories. In any actual particular domain directory tree, this whole hierarchy might not be present.
This section describes the contents of the domain directory and its subfolders. Note that the domain-name, server-name, and deployment-name directory names are not literal, but are replaced with whatever specific names is appropriate; other directory names are literal.
This directory provides a quick way to deploy applications in a development server. When the WebLogic Server instance is running in development mode, it automatically deploys any applications or modules that you place in this directory.
This directory contains scripts that are used in the process of starting and stopping the Administration Server and the Managed Servers in the domain. These scripts are generally provided as
.sh files for UNIX and
.cmd files for Windows. The
bin directory can optionally contain other scripts of domain-wide interest, such as scripts to start and stop database management systems, full-text search engine processes, etc. For more information, see Managing Server Startup and Shutdown.
This directory contains one application, or deployable module. It contains a subhierarchy that can contain an archive file (EAR or WAR), a deployment plan file, external descriptors, and so on. The directory takes its name from the module's name.
This directory contains system modules for instrumentation in the WebLogic Diagnostic Framework. For more information, see Understanding the WebLogic Diagnostic Framework.
This directory contains system modules for JDBC: global JDBC modules that can be configured directly from JMX (as opposed to JSR-88). For more information, see Database Connectivity (JDBC).
This directory contains system modules for JMS: global JMS modules that can be configured directly from JMX (as opposed to JSR-88). For more information, see Messaging and WebLogic Server (JMS).
This directory holds configuration information for connection to the Node Manager. For more information, see Using Node Manager to Control Servers in Managing Server Startup and Shutdown.
This directory contains system modules for the security framework. It contains one security provider configuration extension for each kind of security provider in the domain's current realm. For more information, see Understanding WebLogic Security.
This directory contains a set of JAR files that save the domain's configuration state. Just before pending changes to the configuration are activated, the domain's existing configuration state, consisting of the
config.xml file and the other related configuration files, is saved in a versioned JAR file with a name like
The maximum number of versioned JAR files to be kept is specified by the
archiveConfigurationCount attribute of
DomainMBean. Once this maximum number is reached, the oldest conversion archive is deleted before a new one is created.
This directory contains domain configuration files representing configuration changes that have been requested, but not yet activated. Once the configuration changes have been activated, the configuration files are deleted from this directory. For more information, see Managing Configuration Changes.
For more information, see Understanding WebLogic Security.
This directory contains one subdirectory for each WebLogic Server instance in the domain. For more information, see A Server's Root Directory.
This directory holds executable or shell files that can be or must be different for each server. The server environment script (
setServerEnv.cmd) is an example of a file that resides here because it can differ from one WebLogic Server instance to the next, for example, depending on whether the server instance has its own startup plan.
This directory holds directories and files that contain cached data. By "cached" here we mean that the data is a copy, possibly in a processed form (compiled, translated, or reformatted), of other data.
This directory holds files that maintain persistent per-server state used to run the WebLogic Server instance, other than security state, as opposed to temporary, cached or historical information. Files in this directory are important data that must be retained as the WebLogic Server instance is brought up, is brought down, crashes, restarts, or is upgraded to a new version.
This directory holds WebLogic persistent stores. For each persistent store, there is a subdirectory that holds the files that represent the persistent store. The name of the subdirectory is the name of the persistent store. By convention there is one store named
This directory holds logs and diagnostic information. This information is historical in nature. It is not crucial to the operation of the server, and can be deleted (while the WebLogic Server instance is down, at least) without affecting proper operation. However, the information can be quite useful for debugging or auditing purposes and should not be deleted without good reason.
This directory holds information created by the Server Image Capture component of the WebLogic Diagnostic Framework. For more information, see Understanding the WebLogic Diagnostic Framework.
This directory contains one subdirectory for each JMS server in the WebLogic Server instance. Each such subdirectory contains the logs for that JMS server. The name of the subdirectory is the name of the JMS server.
This directory holds security-related files that can be or must be different for each WebLogic Server instance. The file
boot.properties is an example of a file that resides here because it can differ from one server to the next. This directory also maintains files related to SSL keys.
This directory holds temporary directories and files that are created while a server instance is running. For example, a JMS paging directory is automatically created here unless another location is specified. Files in this directory must be left alone while the server is running, but may be freely deleted when the server instance is shut down.
By default, configuration information is automatically copied from the Administration Server to each Managed Server. If instead you prefer to stage configuration changes manually, you can use this directory as an alternative to the
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. 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.
pathoption when starting a WebLogic Server instance from command line. For example the following command:
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.
pathoption, then the value of
pathis the server root directory.
pathis not specified, then the working directory is the server root directory. However, if you are upgrading a domain created under WebLogic Server 6.x, then the server root directory is the parent of the working 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.
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:
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.
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:
pathoption, then the value of
pathis the server's root directory.
pathis not specified, then the working (current) directory is the root directory. For example, if you run the
c:\config\MyManagedServeris the root directory.
To make it easier to maintain your domain configurations and applications across upgrades of WebLogic Server software, it is recommended that the server root directory not be the same as the installation directory for the WebLogic Server software.