4 Managing Configuration Changes

To provide a secure, predictable means for distributing configuration changes in a domain, Oracle WebLogic Server imposes a change management process that loosely resembles a two-phase commit database transaction. The following sections describe configuration change management:

Overview of Change Management

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 Example 4-0). To edit these Configuration MBeans, you use a JMX client (either the Administration Console, WLST, or a client that you create) to obtain a lock.

While you have the lock on the editable Configuration MBeans, you can save your in-memory changes, which causes 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 active 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).

Note that 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 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 Oracle Fusion Middleware Introduction to Oracle WebLogic Server, you can use a variety of different Oracle WebLogic Server tools to make configuration changes:

  • Administration Console

  • 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 detailed information about how configuration changes are carried out through JMX and Configuration MBeans, see "Understanding WebLogic Server MBeans" in Oracle Fusion Middleware Developing Custom Management Utilities With JMX for Oracle WebLogic Server. For more detailed information about making configuration changes with WLST, see "Configuring Existing Domains" in Oracle Fusion Middleware Oracle 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 Oracle Fusion Middleware Securing 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 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 Fusion Middleware Oracle WebLogic Server Administration Console Help.

As you make configuration changes using the Administration Console, you click Save on the appropriate pages. This does not cause the changes to take effect 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 of the changes are rolled back from all of 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 Administration Console has an auto-activate model. Instead of clicking Activate Changes, your changes will be automatically activated when you save them. This is the default behavior in development domains; it cannot be enabled in production domains. You can disable this behavior by deselecting the Automatically Acquire Lock and Activate Changes Console preference option.

Configuration Change Management Process

Configuration changes happen in basically the same way, regardless of the JMX tool you choose to use (the Administration Console, WLST, or JMX APIs). The following steps describe the process in detail, starting from when you first boot the domain's Administration Server:

  1. When the Administration Server starts, it reads the domain's configuration files, including 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 Administration Console, 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 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 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.

  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 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 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 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.

For information about the compatibility MBean server, which is used with the deprecated weblogic.management.MBeanHome interface, see "Deprecated MBeanHome and Type-Safe Interfaces" in Oracle Fusion Middleware Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

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, which 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.

Note that once you have set your domain to be read-only, you can no longer edit its configuration using the 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 should also 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 Oracle Fusion Middleware Securing Oracle WebLogic Server.