4 Managing Configuration Changes

The change management process in Oracle WebLogic Server provides a secure and predictable means for distributing configuration changes in domains. In this process, in-memory changes can be made using editable Configuration MBeans.

This chapter includes the following sections:

Overview of Change Management

To provide a secure, predictable means for distributing configuration changes in a domain, WebLogic Server imposes a change management process that loosely resembles a database transaction. 

Each domain describes its configuration in an XML document that is located in the domain's configuration directory. At run time, each Oracle WebLogic Server instance in a given domain creates an in-memory representation of the configuration described in this document. The in-memory representation of a domain's configuration is a collection of read-only managed beans (MBeans) called Configuration MBeans.

In addition to the read-only Configuration MBeans, the Administration Server maintains another collection of Configuration MBeans that you can edit (see Figure 4-2). To edit these Configuration MBeans, you obtain a lock using any of the administration tools listed in Summary of System Administration Tools and APIs in Understanding Oracle WebLogic Server.

While you have the lock on the editable Configuration MBeans, you can save your in-memory changes, which cause the Administration Server to write the changes to a set of pending configuration documents in the domain directory. Oracle WebLogic Server instances do not consume the changes until you activate the changes.

When you activate changes, each server in the domain determines whether it can accept the change. If all servers are able to accept the change, they update their copy of the domain's configuration document. Then they update their working copy of Configuration MBeans and the change is completed (see Figure 4-3).

Oracle WebLogic Server's change management process applies to changes in domain and server configuration data, not to security or application data.

Changes Requiring Server Restart

Some configuration changes can take effect on the fly, while others require the affected servers to be restarted before they take effect. Configuration changes that can take effect without a server restart are sometimes referred to as dynamic changes; configuration changes that require a server restart are sometimes referred to as non-dynamic changes. In the WebLogic Server Administration Console, an attribute that requires a server restart for changes to take effect is marked with this icon: Server Restart Required Icon

Edits to dynamic configuration attributes become available once they are activated, without restarting the affected server or system resource. Edits to non-dynamic configuration attributes require that the affected servers or system resources be restarted before they become effective.

If an edit is made to a non-dynamic configuration setting, no edits to dynamic configuration settings will take effect until after restart. This is to assure that a batch of updates having a combination of dynamic and non-dynamic attribute edits will not be partially activated.

Configuration Change Tools

As described in Summary of System Administration Tools and APIs in Understanding Oracle WebLogic Server, you can use a variety of different Oracle WebLogic Server tools to make configuration changes:

  • WebLogic Server Administration Console

  • Fusion Middleware Control (FMWC)

  • WebLogic Scripting Tool

  • JMX APIs

Whichever tool you use to make configuration changes, Oracle WebLogic Server handles the change process in basically the same way.

For more information about how configuration changes are carried out through JMX and Configuration MBeans, see Understanding WebLogic Server MBeans in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server. For more information about making configuration changes with WLST, see Configuring Existing Domains in Understanding the WebLogic Scripting Tool.

Configuration Auditing

Using the WebLogic Auditing provider or another auditing security provider, you can record audit information about changes made to your Oracle WebLogic Server configuration. See Enabling Configuration Auditing in Administering Security for Oracle WebLogic Server.

Change Management in the Administration Console

The WebLogic Server Administration Console centralizes the configuration change management process in the Change Center pane.

If you want to use the WebLogic Server Administration Console to make configuration changes, you must first click the Lock & Edit button in the Change Center. When you click Lock & Edit, you obtain a lock on the editable collection of Configuration MBeans for all servers in the domain (the edit tree).

Note:

The domain configuration locking feature is always enabled in production domains. It can be enabled or disabled in development domains. It is disabled by default when you create a new development domain. See Enable and disable the domain configuration lock in Oracle WebLogic Server Administration Console Online Help.

As you make configuration changes using the WebLogic Server Administration Console, you click Save on the appropriate pages. However, the changes do not reflect immediately. Instead, when you click Save, you are saving the change to the edit tree and to the DOMAIN_NAME/pending/config.xml file and related configuration files. The changes take effect when you click Activate Changes in the Change Center. At that point, the configuration changes are distributed to each of the servers in the domain. If the changes are acceptable to each of the servers, then they take effect. (Note, however, that some changes require a server to be restarted.) If any server cannot accept a change, then all the changes are rolled back from all the servers in the domain. The changes are left in a pending state; you can then either edit the pending changes to resolve the problem or revert the pending changes.

For development domains, the WebLogic Server Administration Console has an auto-activate model. Instead of clicking Activate Changes, your changes are automatically activated when you save them. This behavior is default in development domains and it cannot be enabled in production domains. You can disable this behavior by deselecting the Automatically Acquire Lock and Activate Changes Console preference option.

Taking the Configuration Lock From Another Administrator

In the WebLogic Server Administration Console, an administrator can take a configuration lock from another administrator, make configuration changes, and save these changes. See Take configuration lock from another administrator in the Oracle WebLogic Server Administration Console Online Help. The administrator you take the lock from will not be able to make any additional changes unless they take the lock back or you submit your changes and release the lock.

If the administrator you take the lock from was using the WebLogic Server Administration Console to make changes, you will inherit any pending changes. If the other administrator is using another method to make configuration changes, such as WLST, these changes may be lost when you take the lock.

Configuration Change Management Process

Configuration changes happen in basically the same way, regardless of the method you choose to use (the WebLogic Server Administration Console, FMWC, WLST, JMX or REST APIs).

The following steps describe the process in detail, starting from when you first boot the domain's Administration Server:

Note:

Do not add non-configuration files in the config directory or subdirectories. Non-configuration files include log (.log) and lock (.lck) files. Administration Server replicates the config directory in all Managed Server instances. Storing non-configuration files in the config directory can cause performance issues in the domain.

  1. When the Administration Server starts, it reads the domain's configuration files, including the config.xml file and any subsidiary configuration files referred to by the config.xml file and uses the data to instantiate the following MBean trees in memory:

    • A read-only tree of Configuration MBeans that contains the current configuration of resources that are on the Administration Server.

    • An editable tree of all Configuration MBeans for all servers in the domain.

      Note:

      The Administration Server also instantiates a Runtime MBean tree and a DomainRuntime MBean tree, but these are not used for configuration management.

  2. To initiate a configuration change, you do the following:

    1. Obtain a lock on the current configuration.

    2. Make any changes you desire, using the tool of your choice (the WebLogic Server Administration Console, FMWC, WLST, the JMX APIs, and such).

    3. Save your changes to a pending version of the config.xml file, using the Save button in the WebLogic Server Administration Console; using the WLST save command; or using the save operation on the ConfigurationManagerMBean.

  3. The Configuration Manager service saves all data from the edit MBean tree to a separate set of configuration files in a directory named pending. See Figure 4-2.

    The pending directory is immediately below the domain's root directory. For example, if your domain is named mydomain, then the default pathname of the pending config.xml file is mydomain/pending/config.xml.

    Figure 4-2 The Administration Server's Pending config.xml File

    Description of Figure 4-2 follows
    Description of "Figure 4-2 The Administration Server's Pending config.xml File"
  4. Make additional changes or undo changes that you have already made.

  5. When you are ready, activate your changes in the domain, using the Activate Changes button in the WebLogic Server Administration Console's Change Center; using the WLST activate command; or using the activate operation on the ConfigurationManagerMBean.

    When you activate changes (see Figure 4-3):

    1. For each server instance in the domain, the Configuration Manager service copies the pending configuration files to a config directory in the server's root directory.

      If a Managed Server shares its root directory with the Administration Server, ConfigurationManagerMBean does not copy the pending configuration files; the Managed Server uses the Administration Server's config directory.

    2. Each server instance compares its current configuration with the pending configuration.

    3. Subsystems within each server vote on whether they can consume the new configuration.

      If any subsystem indicates that it cannot consume the changes, the entire activation process is rolled back and the ConfigurationManagerMBean emits an exception. You can modify your changes and retry the change activation, or you can abandon your lock, in which case the edit Configuration MBean tree and the pending configuration files are reverted to the configuration in the read-only Configuration MBean tree and configuration files.

    4. If all subsystems on all servers can consume the change, the Configuration Manager service replaces the read-only configuration files on each server instance in the domain with the pending configuration files.

    5. Each server instance updates its beans and its read-only Configuration MBean tree according to the changes in the new configuration files. In cases that include one or more changes that require the server to be restarted, this occurs the next time the server is restarted.

    6. The pending configuration files are then deleted from the pending directory.

      Note:

      If the Administration Server crashes before completing activation of your changes (step 5.f), upon restart, the Administration Server will recover the pending configuration files saved in step 5.a. In the log file, this process is referred to as config recovery.

  6. You can retain your lock to make additional changes or release it so that others can update the configuration. You can configure a time-out period that causes the Configuration Manager service to abandon a lock.

Figure 4-3 Activating Changes in Managed Servers

Description of Figure 4-3 follows
Description of "Figure 4-3 Activating Changes in Managed Servers"

Configuration Locks

When you start an edit session, whether you use the WebLogic Server Administration Console, WLST, or the Management APIs, you obtain a lock on the Configuration MBean edit tree.

The configuration change lock does not by itself prevent you from making conflicting configuration edits using the same administrator user account. For example, if you obtain a configuration change lock using the WebLogic Server Administration Console, and then use the WebLogic Scripting Tool with the same user account, you will access the same edit session that you opened in the WebLogic Server Administration Console and you will not be locked out of making changes with the Scripting Tool. You can reduce the risk that such a situation might occur by maintaining separate administrator user accounts for each person with an administrative role. Similar problems can still occur, however, if you have multiple instances of the same script using the same user account.

To reduce further the risk of this situation, you can obtain an exclusive configuration change lock. When you have an exclusive configuration lock, a subsequent attempt to start an edit session by the same owner will wait until the edit session lock is released. To obtain an exclusive configuration lock using WLST, use true for the exclusive argument in the startEdit command:

wls:/mydomain/edit> startEdit(60000, 120000, true)

To obtain an exclusive configuration lock using the Management API, use true for the exclusive parameter in the ConfigurationMBean.startEdit operation:

Object [] startEdit(60000, 120000, true)

You cannot modify the domain configuration using the compatibility MBean server when either of the following is true:

  • there is an existing editing session, or

  • there are pending changes saved, but not yet activated from a previous edit session.

Resolving Change Conflicts

In the event that you have saved more than one change set without activating them and one change would invalidate a prior change, the Change Management service requires you to manually resolve the invalidation before it will save your changes.

Configuration Management State Diagram

The Configuration Management service follows a series of states.

These states are described in Figure 4-4.

Figure 4-4 Configuration Management State Diagram

Description of Figure 4-4 follows
Description of "Figure 4-4 Configuration Management State Diagram"

Restricting Configuration Changes

You can block configuration changes by setting a domain to be read-only. Do this by setting the EditMBeanServerEnabled attribute of the JMXMBean configuration MBean to false, using either WLST or the Management APIs.

Once you have set your domain to be read-only, you can no longer edit its configuration using the WebLogic Server Administration Console, WLST online, or the Management APIs. To make the domain editable again, you must either edit the config.xml file directly in a text editor, or use WLST offline, and then restart the affected servers.

You must establish appropriate access controls to the domain's configuration, limiting access to users with the proper security roles. In addition, using the WebLogic Auditing provider or another auditing security provider, you can record audit information about changes made to your Oracle WebLogic Server configuration. See Enabling Configuration Auditing in Administering Security for Oracle WebLogic Server.

Configuration Overriding

Configuration overriding lets administrators place configuration information, contained in an XML file, in a known location where running servers identify and load it, overriding aspects of the existing configuration.

In large clusters or complex distributed environments, such as in cloud platforms, setting and removing configuration properties can be challenging due to network, software, and scaling issues. Situations arise where you might want or need to run your servers in Managed Server Independence Mode (MSI) mode. You can use configuration overriding (also called situational configuration) to change settings such as server debugging flags, timeout values, or diagnostics settings, without running the Administration Server. The configuration overrides are targeted to Managed Servers but can also be applied to the Administration Server. When using configuration overriding, there is no synchronization between the Administration Server and Managed Servers. Configuration overriding bypasses the Administration Server as the primary means of distributing configuration information to Managed Servers.

Situational configuration lets you place a file containing configuration changes (overrides) that need to be added to a running WebLogic Server instance. The overrides may have an expiration time to ensure that the configuration changes do not remain in effect longer than necessary or they can be permanent; no expiration time is specified. In an earlier release of WebLogic Server, an overridden domain configuration required an expiration time and was therefore always temporary. However, this limitation is now removed. For more information, see “Temporary Configuration Overriding” in Understanding Domain Configuration for Oracle WebLogic Server.

Consider this scenario. In certain environments, you might want to allow for different size clusters. You could have a base configuration for all environments, combined with configuration overrides that provide the appropriate configurations for small, medium, or large clusters. This allows the common, shared configuration to be separate from the cluster-size specific configurations. For example, certain servers are needed only in the large cluster environment. In the small cluster environment, the administrator does not want these servers to be present. The administrator creates a situational configuration file that deletes the servers. At runtime, the situational configuration file is loaded and the unwanted servers are removed from the configuration.

Situational configuration:

  • Applies a configuration change to a running system; it does not impact the stored configuration.

  • Employs an XML fragment, in a file, which contains values to be changed and context information. The file is used to update configuration information coming from the config.xml file or system resource files that exist in the jdbc, jms, and diagnostics subdirectories of the domain config directory.

  • Can replace configuration element values, add new configuration elements, or delete existing configuration elements.

  • Can update dynamic and non-dynamic attributes. However, when changes include non-dynamic modifications that were applied after the server was started, the server will not update a situational configuration change until the next server start.

  • May contain an expiration time for the configuration override, but it is not required. Overrides are reverted when the XML file is removed, renamed, or expired.

  • Contains an option to require that situational configuration files be present, and if not found, then the server startup fails.

  • Does not require involvement by the Administration Server and the Managed Servers do not synchronize their values in any way.

If a value which is currently overridden by a situational configuration is changed in an edit session, that change will not take effect until the situational configuration overrides are removed. Situational configuration will log a message in the server's log when it is applied and expired or removed.

About Situational Configuration Files, Names and Locations

Situational configuration files end with the suffix "situational-config.xml" and are domain configuration files, which, by default, reside in an optconfig directory. In the case of JDBC, JMS, and diagnostic system resources, they reside in jdbc, jms, and diagnostics subdirectories of optconfig.

Figure 4-5 Domain Configuration File Directories Layout



Administrators create, update, and delete situational-config.xml files. If the domains are located on separate systems, the situational configuration XML files must be copied into each optconfig directory.

For JDBC, JMS, and diagnostic system resource files, the situational configuration file name must match the system resource file name, then add the situational-config.xml suffix. For example, a JMS system resource named myqueues-jms.xml, can be overridden only by a file with the name myqueues-jms-situational-config.xml.

Overriding the Default File Location

Using the system property, weblogic.SituationalConfigPath, you can override the default optconfig directory location for situational-config.xml files.

To set the value, use: export JAVA_OPTIONS=-Dweblogic.SituationalConfigPath=<your sitconfig file path> and then start the server.

For example:

export JAVA_OPTIONS=-Dweblogic.SituationalConfigPath=$optconfig:$domainroot/mydir:/scratch/myoptconfig

The following substitutions are supported:

  • $domainroot - the domain root directory

  • $optconfig - the default location for optconfig, for example, $domainroot/optconfig

You can locate situational-config.xml files in server-specific directories under a defined optconfig directory. For example, the Administration Server will look for situational configuration files in $domainroot/optconfig and $domainroot/optconfig/admin. On a Managed Server, ms1, the server will look for situational configuration files in $domainroot/optconfig and $domainroot/optconfig/ms1.

For server-specific system resource situational configuration files, you can specify jdbc, jms, and diagnostics subdirectories in server-specific directories under a defined optconfig directory.

The system property can be a colon-separated list of paths, for example: $optconfig:$domainroot/mydir:/scratch/myoptconfig. Given this example path, the server will look for (process) situational configuration files in the following order:

<domain root>/optconfig
<domain root>/optconfig/<servername>
<domain root>/optconfig/jms
<domain root>/optconfig/jdbc
<domain root>/optconfig/diagnostics

<domain root>/mydir/
<domain root>/mydir/<servername>
<domain root>/mydir/jms
<domain root>/mydir/jdbc
<domain root>/mydir/diagnostics

/scratch/myoptconfig
/scratch/myoptconfig/<servername>
/scratch/myoptconfig/jms
/scratch/myoptconfig/jdbc
/scratch/myoptconfig/diagnostics
File Format

A situational configuration file contains an XML fragment that references the structure of the configuration it is modifying. For example, to modify this server’s debug configuration in config.xml:

<domain .... >
  <name>sitconfigDomain</name>
  <server>
    <name>admin</name>
    <server-debug>
    </server-debug>
  </server>
...

The situational configuration XML fragment would look like this:

<?xml version='1.0' encoding='UTF-8'?>
<dom:domain
 xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
 xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
 xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
   <s:expiration> 2020-11-29T10:24-08:00 </s:expiration>
  <dom:name>sitconfigDomain</dom:name>
  <dom:server>
    <dom:name>admin</dom:name>
    <dom:server-debug>
      <dom:debug-jmx-core f:combine-mode="replace">true</dom:debug-jmx-core>
    </dom:server-debug>
  </dom:server>
  </dom:domain>

In the following example, debug-jmx-core, is not replaced (overridden) because part of the path (<server-debug>) is missing.

<f:domain  xmlns=.... >
   <dom:server>
     <dom:name>admin</dom:name>
      <dom:debug-jmx-core f:combine-mode="replace">true</dom:debug-jmx-core>
   </dom:server>
</f:domain>

Schemas

Situational configuration XML fragments include entries from multiple schemas. The situational-config schema provides information on how the situational configuration will be applied; for example, its expiration time. The rest of the fragment contains information on how to modify the in-memory contents of config.xml or system resource file.

The situational-config.xsd contains these lines:

    <?xml version="1.0" encoding="UTF-8" ?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
         <!-- expiration time for this file -->
        <xs:element name=“expiration” type=“xs:string”/>
    </xs:schema>

sit-domain-fragment.xsd is not a “true” schema but it must be referenced in the XML fragment. Use the syntax f:combine-mode="replace" to replace (override) values, as shown in the following example:

    <?xml version='1.0' encoding='UTF-8'?>
    <f:domain 
     xmlns="http://xmlns.oracle.com/weblogic/domain" 
     xmlns:f="http://xmlns.oracle.com/weblogic/sit-domain-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
       <s:expiration> 2020-07-16T19:20+01:00 </s:expiration>
       <server>
         <name>soa_server1</name>
         <max-message-size f:combine-mode="replace">30000000</max-message-size>
        <server-debug>
          <debug-jmx-core f:combine-mode="replace">true</debug-jmx-core>
        </server-debug>
       </server>
    </f:domain>

Situational configuration fragments for system resources are similar to the situational configuration files for config.xml overrides. For JDBC, JMS, and diagnostic system resource files, the XML situational configuration and namespaces are specific to the system resource type (JMS, JDBC, or WLDF). The rest of the fragment contains information on how to modify the in-memory contents of the system resource. Consider the following example situational configuration files for JMS, JDBC, and WLDF system resources.

  • A JMS situational configuration file that overrides the shared configuration element and the expiration policy:
    <?xml version='1.0' encoding='UTF-8'?>
    <jms:weblogic-jms
     xmlns:jms="http://xmlns.oracle.com/weblogic/weblogic-jms"
     xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-jms-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
     <jms:quota jms:name="MyTemplate.Quota">
        <jms:shared f:combine-mode="replace">true</jms:shared>
     </jms:quota>
      <jms:template jms:name="MyTemplate">
        <jms:delivery-failure-params>
          <jms:expiration-policy f:combine-mode="replace">Discard</jms:expiration-policy>
        </jms:delivery-failure-params>
      </jms:template>
    </jms:weblogic-jms>
  • A JDBC file that adds a user name and password property:
    <?xml version='1.0' encoding='UTF-8'?>
    <jdbc:jdbc-data-source
     xmlns:jdbc="http://xmlns.oracle.com/weblogic/jdbc-data-source"
     xmlns:f="http://xmlns.oracle.com/weblogic/jdbc-data-source-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
     <jdbc:name>jdbcDataSource</jdbc:name>
       <jdbc:jdbc-driver-params>
         <jdbc:properties>
           <jdbc:property f:combine-mode="replace">
              <jdbc:name>user</jdbc:name>
              <jdbc:value>Jones</jdbc:value>
           </jdbc:property>
           <jdbc:property f:combine-mode="replace">
              <jdbc:name>password</name>
              <jdbc:value>password</value>
           </jdbc:property>
         </jdbc:properties>
       </jdbc:jdbc-driver-params>
    </jdbc:jdbc-data-source>
  • A diagnostics file that enables instrumentation:
    <?xml version='1.0' encoding='UTF-8'?>
    <wldf-resource
      xmlns:wldf="http://xmlns.oracle.com/weblogic/weblogic-diagnostics"
      xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-diagnostics-fragment"
      xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
      <wldf:instrumentation>
        <wldf:enabled f:combine-mode="replace">true</wldf:enabled>
      </wldf:instrumentation>
    <wldf:wldf-resource>

To add or delete configuration elements, use the syntax, f:combine-mode="add" or f:combine-mode="delete", as shown in the following examples.

  • The following configuration file fragments demonstrate adding both basic datatypes (String, int, Boolean) and arrays of nested elements. Elements are added at both the domain and nested server layer:
    <?xml version='1.0' encoding='UTF-8'?>
    <dom:domain
     xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
     xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
      <s:expiration> 2020-11-30T19:20+01:00 </s:expiration>
      <dom:name>sitconfigDomain</dom:name>
      <dom:notes f:combine-mode="add">Situational Config Domain</dom:notes>
      <dom:archive-configuration-count f:combine-mode="add">2</dom:archive-configuration-count>
      <dom:startup-class f:combine-mode="add">
        <dom:deployment-order>33</dom:deployment-order>
        <dom:name>AddedStartupClassOne</dom:name>
      </dom:startup-class>
      <dom:startup-class f:combine-mode="add">
        <dom:deployment-order>44</dom:deployment-order>
        <dom:name>AddedStartupClassTwo</dom:name>
      </dom:startup-class>
      <dom:server>
        <dom:name>admin</dom:name>
        <dom:notes f:combine-mode="add">admin server</dom:notes>
        <dom:server-debug>
          <dom:debug-jmx-core f:combine-mode="add">true</dom:debug-jmx-core>
        </dom:server-debug>
        <dom:max-message-size f:combine-mode="add">78787878</dom:max-message-size>
      </dom:server>
    </dom:domain>
  • The following configuration file fragments demonstrate adding a new server to the domain:
    <?xml version='1.0' encoding='UTF-8'?>
    <dom:domain
      xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
     xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
      <s:expiration> 2020-11-30T19:20+01:00 </s:expiration>
      <dom:name>sitconfigDomain</dom:name>
      <dom:server f:combine-mode="add">
        <dom:name>addedServer</dom:name>
        <dom:notes>addedServer notes</dom:notes>
        <dom:listen-port>7401</dom:listen-port>
        <dom:tgiop-enabled>false</dom:tgiop-enabled>
        <dom:network-access-point>
          <dom:name>AddedNetworkAccessPointOne</dom:name>
          <dom:listen-port>7501</dom:listen-port>
        </dom:network-access-point>
        <dom:network-access-point>
          <dom:name>AddedNetworkAccessPointTwo</dom:name>
          <dom:listen-port>7601</dom:listen-port>
        </dom:network-access-point>
      </dom:server>
    </dom:domain>
  • The following configuration file fragments demonstrate deleting both basic datatypes (String, int, Boolean). Elements are deleted at both the domain and nested server layer:
    <?xml version='1.0' encoding='UTF-8'?>
    <dom:domain
      xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
     xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
      <s:expiration> 2020-11-30T19:20+01:00 </s:expiration>
      <dom:name>sitconfigDomain</dom:name>
      <dom:configuration-version f:combine-mode="delete"></dom:configuration-version>
      <dom:server>
        <dom:name>MyServerOne</dom:name>
        <dom:listen-port f:combine-mode="delete"></dom:listen-port>
        <dom:network-access-point f:combine-mode="delete"></dom:network-access-point>
       </dom:server>
      <dom:server>
        <dom:name>MyServerTwo</dom:name>
        <dom:listen-port f:combine-mode="delete"></dom:listen-port>
      </dom:server>
      <dom:server>
        <dom:name>ms1</dom:name>
        <dom:accept-backlog f:combine-mode="delete"></dom:accept-backlog>
        <dom:ignore-sessions-during-shutdown f:combine-mode="delete"></dom:ignore-sessions-during-shutdown>
      </dom:server>
    </dom:domain>

XML Namespaces

The following table summarizes the XML namespaces used by situational configuration files.

xmlns Type Example Description

Domain

xmlns:dom="http://xmlns.oracle.com/weblogic/domain"

Used for domain situational config.xml overrides to identify domain elements, for example, <dom:domain>.

Domain Fragment

xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"

Used for domain config.xml overrides to identify domain fragment elements, for example, f:combine-mode="replace" inside a domain element.

Situational Configuration

xmlns:s="http://xmlns.oracle.com/weblogic/situational-config"

Used for domain config.xml and system resource overrides to identify situational configuration elements, for example, <s:expiration-time>.

JMS

xmlns:jms="http://xmlns.oracle.com/weblogic/weblogic-jms"

Used to identify JMS system resource elements, for example, <jms:template name="JMSTemplate1">.

JDBC

xmlns:jdbc="http://xmlns.oracle.com/weblogic/jdbc-data-source"

Used to identify JDBC system resource elements, for example, <jdbc:jdbc-driver-params>.

Diagnostics

xmlns:wldf="http://xmlns.oracle.com/weblogic/weblogic-diagnostics"

Used to identify WLDF system resource elements, for example, <wldf:watch-notification>.

JMS System Resource Fragment

xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-jms-fragment"

Used for JMS system resource overrides to identify JMS system resource fragment elements, for example, f:combine-mode="replace" inside a JMS system resource element.

JDBS System Resource Fragment

xmlns:f="http://xmlns.oracle.com/weblogic/jdbc-data-source-fragment"

Used for JDBC system resource overrides to identify JDBC system resource fragment elements, for example, f:combine-mode="replace" inside a JDBC system resource element.

WLDF System Resource Fragment

xmlns:f="http://xmlns.oracle.com/weblogic/weblogic-diagnostics-fragment"

Used for WLDF system resource overrides to identify WLDF system resource fragment elements, for example, f:combine-mode="replace" inside a WLDF system resource element.

File Expiration

If desired, you can set an explicit expiration time in the XML fragment file by referencing the situational-config.xsd schema and then setting the expiration time element. The expiration time is either a long (system time) or a W3C complaint String.

For example:
   <s:expiration> 2020-11-29T10:24-08:00 </s:expiration>
        11/29/2020 @ 10:24 am (PDT)

   <s:expiration> 2020-11-29T10:24 </s:expiration>
        11/29/2020 @ 10:24 am (local timezone)

   <s:expiration> 2020-11-29T10:24:15 </s:expiration>
        11/29/2020 @ 10:24:15 am (local timezone)

The situational configuration values will be in place until either the file is removed or the system time exceeds the expiration time. After that happens, the file and its values will be unloaded and the settings will return to their previous values. If the situational configuration file has a timeout value which is earlier than the current time (the file has expired), the contents of the file will be ignored.

To enable a permanent situational configuration file with no expiration, specify either no expiration element or an expiration element value of minus one (-1).
  • An example permanent situational configuration file with no expiration element:
    <?xml version='1.0' encoding='UTF-8'?>
    <domain
      xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
     xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
      <name>sitconfigDomain</name>
      <server>
        <name>admin</name>
        <server-debug>
          <debug-jmx-core f:combine-mode="replace">true</debug-jmx-core>
        </server-debug>
      </server>
    </domain>
  • An example permanent situational configuration file with an expiration of -1:
    <?xml version='1.0' encoding='UTF-8'?>
    <dom:domain
      xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
     xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
     xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
      <s:expiration>-1</s:expiration>
      <dom:name>sitconfigDomain</dom:name>
        <dom:server>
          <dom:name>admin</dom:name>
          <dom:server-debug>
            <dom:debug-jmx-core f:combine-mode="replace">true</dom:debug-jmx-core>
          </dom:server-debug>
        </dom:server>
      </dom:domain>

Loading Situational Configurations

The situational configuration file exists when a server is started. Situational configurations are loaded into the runtime hierarchy, not the edit configuration hierarchy. Administrators can see the effective configuration (base configuration + situational configuration overrides) by looking at the runtime tree. The configuration edit tree shows only the base values before the situational configuration was applied or after the situational configuration is removed.

Figure 4-6 Loading and Removal of Situational Configuration Files



Accessing the Edit and Runtime Configuration Using WLST

Given:

  • A config.xml with a domain Notes attribute, "My Domain"

  • A situational configuration file that overrides the domain Notes attribute with the value, "My New Domain"

Using WLST, you can access the values in the runtime and edit configurations as follows:

# runtime configuration
serverConfig()
wls:/mydomain/serverConfig/> print cmo.getNotes()
My New Domain
# edit configuration
wls:/mydomain/serverConfig/> edit()
wls:/mydomain/edit/> print cmo.getNotes()
My Domain
Processing Multiple Fragments

Each situational configuration XML fragment is stored in its own situational-config.xml file; only one fragment per file is allowed. If multiple fragments are available, there will be multiple situational configuration files, each named uniquely. For example:

wildcard-situational-config.xml
example1-situational-config.xml
foobar-situational-config.xml

Situational configuration files are loaded based on their modification date, such that the oldest file is loaded first, then subsequent files are processed (loaded).

Using Wildcards

In XML fragments, you can use wildcards to make them more flexible, such as, to process the same set of configuration settings on multiple resources.

For example, to override identical debug settings on all servers in a cluster:

<f:domain 
  xmlns=.... >
    <dom:server>
     <dom:name>'*'</dom:name>
     <dom:max-message-size f:combine-mode="replace">30000000</dom:max-message-size>
      <dom:server-debug>
               <dom:debug-jmx-core f:combine-mode="replace">true</dom:debug-jmx-core>
      </dom:server-debug>
   </dom:server>
</f:domain>

Only one wildcard is supported, '*' (an asterisk, escaped within single quotation marks). It matches everything.

Follow these rules when using wildcards:

  • Use wildcards in elements only.
    • Wildcards let you replace a specific element with an asterisk (*) and have it match any element within the same set of tags.

    • The wildcard can match any element. For example, if you change the server name, admin, to *, any settings in the fragment which were targeted for admin would now be applied to all servers. For example:  <name>’*’</name> 

  • Tags cannot contain wildcards. The following is not supported: <’*’>admin</’*’>

  • Elements which are to be modified (overridden) cannot have wildcards. The following are not supported:
                   <dom:debug-jmx-core f:combine-mode='*'>'*'</dom:debug-jmx-core>
                   <dom:debug-jmx-core f:combine-mode="replace">'*'</dom:debug-jmx-core>
  • A wildcard replaces a whole word (all or nothing); there are no partial matches. For example, if the string is LKS, * will match; L* or LK* will not match and generate an error.

  • You can use wildcards to add or delete elements. However, because only asterisk ('*') is supported, the add or delete applies to all MBeans. For example, if used with a Server MBean, this action would delete all the servers in the domain. Consider the following examples.
    • The following configuration file fragments demonstrate the use of a wildcard to add basic datatype and container elements to all servers in the domain.
      <?xml version='1.0' encoding='UTF-8'?>
      <dom:domain
        xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
       xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
       xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
        <s:expiration> 2020-11-30T19:20+01:00 </s:expiration>
        <dom:name>sitconfigDomain</dom:name>
        <dom:server>
          <dom:name>'*'</dom:name>
          <dom:notes f:combine-mode="add">wildcard notes</dom:notes>
          <dom:server-debug>
            <dom:debug-jmx-core f:combine-mode="add">true</dom:debug-jmx-core>
          </dom:server-debug>
          <dom:cluster-weight f:combine-mode="add">49</dom:cluster-weight>
            <dom:network-access-point f:combine-mode="add">
              <dom:name>AddedNetworkAccessPoint</dom:name>
              <dom:enabled>false</dom:enabled>
              <dom:listen-port>7501</dom:listen-port>
            </dom:network-access-point>
         </dom:server>
      </dom:domain>
    • The following configuration file fragments demonstrate the use of a wildcard to delete basic datatypes from all servers in the domain.
      <?xml version='1.0' encoding='UTF-8'?>
      <dom:domain
        xmlns:dom="http://xmlns.oracle.com/weblogic/domain"
       xmlns:f="http://xmlns.oracle.com/weblogic/domain-fragment"
       xmlns:s="http://xmlns.oracle.com/weblogic/situational-config" >
        <s:expiration> 2020-11-30T19:20+01:00 </s:expiration>
        <dom:name>sitconfigDomain</dom:name>
        <dom:server>
          <dom:name>'*'</dom:name>
          <dom:accept-backlog f:combine-mode="delete"></dom:accept-backlog>
          <dom:server-debug>
            <dom:debug-jms-back-end f:combine-mode="delete"></dom:debug-jms-back-end>
          </dom:server-debug>
        </dom:server>
      </dom:domain>

Wildcard Overrides

If a file has both wildcard and non-wildcard entries for a value, the first one which matches prevails.

For example:

   <dom:server> 
      <dom:name>server2</dom:name> 
       <dom:max-message-size f:combine-mode="replace">666666</dom:max-message-size>
   </dom:server>     
    <dom:server> 
       <dom:name>'*'</dom:name> 
        <dom:max-message-size f:combine-mode="replace">30000000</dom:max-message-size>
    </dom:server> 
    <dom:server> 
       <dom:name>server1</dom:name> 
        <dom:max-message-size f:combine-mode="replace">9999999</dom:max-message-size>
    </dom:server>

In this example, server2 has a max-message-size of 666666 but server1 has a value of 30000000 (because the * is above server1 in the file).

Monitoring Situational Configuration Changes

Use the ServerRuntimeMBean.isInSitConfigState() method to check if a situational configuration is currently in place. For example:

ServerRuntimeMBean runtimeMBean = runtimeService.getServerRuntime();
    boolean setting = runtimeMBean.isInSitConfigState();

To control how frequently the server polls for situational configuration changes (new, removed, or changed situational-config.xml files), use ServerMBean.setSitConfigPollInterval(int) to configure the polling period (in seconds).

For example, to set the polling rate:

    DomainMBean domainMBean = domainService.getDomainConfiguration();
    ServerMBean serverMBean = domainMBean.lookupServer(adminServerName);
    serverMBean.setSitConfigPollingInterval(value);

Require Situational Configuration

By default, applying a configuration override is optional. Under certain conditions, you might want to require a configuration override, for example, to prevent booting with the default large cluster configuration on a small pod. The SitConfigRequired attribute on the Server MBean controls whether a situational configuration is required or not. This configuration attribute causes the server to not start if no override files are applied. The default is to start the server and not fail.

/**
 * Sets whether situational config files are required. If required, then WebLogic Server will 
 * fail to boot if no situational config files are present. The default is to not require situational config files.
 * @param isRequired - true if situational config files are required, false otherwise.
 * @default false
 * @dynamic
 * @include-api for-public-api
 */
void setSitConfigRequired(boolean isRequired);
 
/**
 * Returns whether situational config files are required and WebLogic Server should fail to boot if situational config files are not present.
 * @return  true if situational config files are required, false otherwise.
 * @dynamic
 * @include-api for-public-api
 */
int isSitConfigRequired();

Using Named Concurrent Edit Sessions

In prior releases, WebLogic Server supported only one active configuration edit session at a time. The system administrator got a global edit lock, made changes, and then activated them. Other administrators could not make changes at the same time. However, now WebLogic Server enables multiple, named concurrent edit sessions, which allows more than one administrator to make configuration changes at the same time.

The concurrent edit sessions are typically useful when multiple administrators work in different parts of the system. Also, when configuring a system takes a long time because of the serial execution of configuration commands, a single administrator can open multiple named edit sessions. This saves time by running the configuration edit sessions in parallel.

In a multitenant environment, more than one administrator needs to make configuration changes concurrently. A multitenant WebLogic domain contains multiple partitions each with its own administrator. Partition administrators must be able to make configuration changes to their partitions and the resources deployed in them without affecting other partition administrators or the WebLogic system administrator. Multiple, named concurrent edit sessions support one or more configuration edit sessions per partition plus global configuration edit sessions.

See Managing Named Concurrent Edit Sessions in Using Oracle WebLogic Server Multitenant.