3 Using OIG Configuration Utility

Oracle WebLogic Server (WLS) has hundreds of configurable values. A specific group of values can affect how a component of the system operates. For example, you can tune database performance by configuring the database settings in WLS.

Oracle provides tuning guides for various components of WLS. Properly tuning a component can consist of performing dozens of steps, with many values to input. It’s possible that entering these values manually can result in input errors, or one or more steps may be missed.

oig-configuration-attributes.json helps avoid manual configuration errors by using the values from an attributes file to configure the WLS system. The utility captures the state of the system before any changes are made, and creates a report that shows the system values before and after a gesture was executed. In the case where a set of changes made the system less stable, the utility allows you to restore the system to a previously captured state.

By default, the values to set are stored in the oig-configuration-attributes.json file in the config/ directory. To make configuration changes: edit oig-configuration-attributes.json, entering the values you want to use for the attributes, and run the OIG Configuration Utility, specifying the gestures and operations to perform.

• Interactive Mode and Silent Mode
  OIG Configuration Utility can be run in two modes: interactive and silent.
• Baselines and Restoration
  OIG Configuration Utility provides the ability to create baseline images of the system configuration. A baseline contains the system state of all attributes that can be modified by all defined operations at the time the baseline is created. You can use a baseline to restore the system to a previous configuration, setting the system attributes to those stored in the specified baseline.
• Gestures and Operations
  The configuration operations that OIG Configuration Utility can perform are defined and implemented by gestures.
• Reports
  When you perform one or more operations using OIG Configuration Utility in interactive mode, before any changes are made to the system, the utility produces a report showing the initial and final attribute values.

Interactive Mode and Silent Mode

OIG Configuration Utility can be run in two modes: interactive and silent.

Interactive mode prompts the user to enter details required by the operation being performed, such as user names and passwords.

Silent mode requires that all necessary input be provided to the utility before being executed—no user interaction is required. This mode is ideal to be paired with a script, which can enable a WebLogic Server admin to offer a configuration service to an end user via a button or link that they press, which in turn performs the configuration.

In both silent and interactive modes, you can specify values for inputs used by one or more operations in the inputs.properties file. In interactive mode, as the operations are executed, the user is prompted to enter any required input values that are not defined in the inputs file. In silent mode, if any required inputs are missing when the utility is called, the call fails.

• Interactive Mode
  Interactive mode prompts you to enter values for require inputs as the utility executes one or more operations. This mode can be convenient for an administrator working on configuring a system from a command prompt.
• Silent Mode
  Silent mode requires that you provide values for all the required inputs of the gesture operations that you want to execute when you launch the utility. If any inputs are missing, the call fails—the utility will not prompt you to enter any missing values. This mode is useful for providing the ability for an end-user to perform a system configuration task. For example, you might create a webpage that includes a button that, when clicked, launches the OIG Configuration Utility in silent mode and performs the desired configuration without the need for user input.

Interactive Mode

Interactive mode prompts you to enter values for require inputs as the utility executes one or more operations. This mode can be convenient for an administrator working on configuring a system from a command prompt.

Invoking OIG Configuration Utility in Interactive Mode

To invoke OIG Configuration Utility in interactive mode, execute the utility without any arguments, using the appropriate script for your environment.

On UNIX, Linux, and Mac OSX systems, run the utility in interactive mode by running the script:

cd $ORACLE_HOME/idm/server/bin/OIGConfigUtility
./oig-config-utility.sh

On Windows systems, run the utility in interactive mode by running the batch file:

cd $ORACLE_HOME\idm\server\bin\OIGConfigUtility
oig-config-utility.bat

For simplicity, other examples in this document demonstrate using the shell script to invoke the utility. On a Windows system, call the batch file, instead.

The basic utility usage information is displayed, and the interactive utility prompt is displayed as:

$oig>

From this prompt, you can enter commands. For example, to display gesture-specific help for the tune gesture, enter the following:

$oig> tune –h

The utility displays the help specific to the tune gesture. You can display the gesture-specific help for any gesture by entering the command gestureName -h. The names of the available gestures are listed in the Configured Gestures section of the utility help.

To run a gesture operation, enter the gesture name and operation, based on the gesture-specific help. For example, you can start the database tuning operation by entering:

$oig> tune –database

As the utility runs the operation, it retrieves any values used by the operation from inputs.properties. For each input where a value is not defined, the utility prompts you to enter a value.

Interactive Mode Options

You can use the following options in Interactive mode.

Option	Description
-a | -all	Use this option to execute all operations defined for all enabled gestures.
-b | -baseline	Use this option to create a baseline of the current system state for all enabled gestures.
-rpt | -report	Use this option to generate a pre-report for all enabled gestures. This report shows the pre- and post-operation values for all enabled gestures, but does not make any changes to the system.
-r | -restore	Use this option to restore the system from a baseline file. This restores the system configuration to that stored in the baseline file. This operation requires a valid file path as input.
-h | -help	Use this option to display help for the OIG Configuration Utility. This includes general instructions for using the utility, as well as which gestures are enabled.
gestureName –h	Use this option to display gesture-specific help for the specified gesture.

Exiting OIG Configuration Utility in Interactive Mode

To exit OIG Configuration Utility, enter quit or q! at the prompt. For example:

$oig> quit

or

$oig> q!

Silent Mode

Silent mode requires that you provide values for all the required inputs of the gesture operations that you want to execute when you launch the utility. If any inputs are missing, the call fails—the utility will not prompt you to enter any missing values. This mode is useful for providing the ability for an end-user to perform a system configuration task. For example, you might create a webpage that includes a button that, when clicked, launches the OIG Configuration Utility in silent mode and performs the desired configuration without the need for user input.

Invoking OIG Configuration Utility in Silent Mode

To invoke OIG Configuration Utility in silent mode, execute the utility with the -S switch, using the appropriate script for your environment.

On UNIX, Linux, and Mac OSX systems, run the utility in silent mode by running the script:

cd $ORACLE_HOME/idm/server/bin/OIGConfigUtility
./oig-config-utility.sh -S

On Windows systems, run the utility in silent mode by running the batch file:

cd $ORACLE_HOME\idm\server\bin\OIGConfigUtility
oig-config-utility.bat -S

For simplicity, other examples in this document demonstrate using the shell script to invoke the utility. On a Windows system, call the batch file, instead.

Running the utility in silent mode with no arguments displays the utility help text. This provides general instructions for using the utility, as well as which gestures are enabled.

When invoking the utility, you must specify which gestures and operations to perform, and provide values for all of the required inputs. These values can be provided as arguments on the command line, as part of inputs.properties, or a combination of both. If any input value is missing or invalid, the utility will exit without making any changes.

You can view the gesture-specific help for any available gesture listed in the utility's help text by entering the command:

./oig-config-utility.sh –S gestureName -h

For example, use the following command to display the gesture-specific help for the tune gesture:

./oig-config-utility.sh –S tune -h

Baselines and Restoration

OIG Configuration Utility provides the ability to create baseline images of the system configuration. A baseline contains the system state of all attributes that can be modified by all defined operations at the time the baseline is created. You can use a baseline to restore the system to a previous configuration, setting the system attributes to those stored in the specified baseline.

You must create a baseline the first time you use OIG Configuration Utility. This creates a backup of your current system, ensuring that you can use the utility to restore your system to this known state, should you make a change that you want to revert.

OIG Configuration Utility includes a restore function that lets you revert the system configuration to that stored in a baseline file.

• Creating a Baseline
  You can use OIG Configuration Utility to create a baseline of your system in both the interactive and silent modes.
• Restoring System from a Baseline File
  You can use the restore feature of OIG Configuration Utility to configure the WebLogic Server with the attribute values from a baseline, backup, or current state file. By default, the files in the backup/, baseline/, and current_state/ directories can all be used to restore a system. The restore option is performed by passing -restore or -r to the utility, followed by the baseline file to use.

Creating a Baseline

You can use OIG Configuration Utility to create a baseline of your system in both the interactive and silent modes.

In interactive mode, start the utility and enter the command -b or -baseline. The utility will prompt you to enter each value that the operation requires that isn't defined in inputs.properties.

In silent mode, start the utility in silent mode with the -b or -baseline switch. For example:

./oig-config-utility.sh –S -baseline

Values that the baseline operation requires must be provided via inputs.properties or as flags passed to the utility (for example, -weblogicPort 1234). The baseline operation fails if any inputs are missing. The baseline files that you create are stored in the baseline/ directory, by default.

In addition to baseline files that you create explicitly, the utility creates a backup of system attributes associated with an operation before attempting the operation (for example, a copy of the database attributes before attempting a database tune operation), and similarly a backup of the current state of the system after an operation has been performed. By default, these files are stored in the backup/ and current_state/ directories, respectively.

Restoring System from a Baseline File

You can use the restore feature of OIG Configuration Utility to configure the WebLogic Server with the attribute values from a baseline, backup, or current state file. By default, the files in the backup/, baseline/, and current_state/ directories can all be used to restore a system. The restore option is performed by passing -restore or -r to the utility, followed by the baseline file to use.

For example, suppose you perform a baseline of your system on July 1, 2018, creating the file oig-baseline_2018-07-01_17_14_19.json in the baseline/ directory. You later make some configuration changes to your database and JVM tuning that have negatively affected your system's performance. You can revert to the old settings by running this command:

./oig-config-utility.sh –S –restore baseline/oig-baseline_2018-07-01_17_14_19.json

Values that the restore operation requires must be provided via inputs.properties or as flags passed to the utility (for example, -weblogicPort 1234). The restore operation fails if any inputs are missing.

Gestures and Operations

The configuration operations that OIG Configuration Utility can perform are defined and implemented by gestures.

OIG Configuration Utility displays which gestures are available in the utility help. This information consists of a short name for the gesture and a description of the gesture. For example, help displays the following information for the tune gesture:

    tune : Tune different components.
        Use 'tune -h' to display gesture-specific help

Here, tune' is the referred to as the short name of the gesture.

To display additional information about a gesture, including which operations the gesture can perform, invoke the utility and pass the gesture short name followed by -h.

To perform a gesture operation using the utility, call the utility specifying the gesture short name and either the operation's short or long CLI flag. The format of this call is:

./oig-config-utility.sh gestureName –<opr_long_flag | opr_short_flag>

For example, the CLI short and long flags (-database and –d) for the database tuning operation are defined in TuneDBOperation.java. To perform a JVM tuning operation in interactive mode, you invoke OIG Configuration Utility by entering one of the following commands:

./oig-config-utility.sh tune –database

using the CLI long flag, or:

./oig-config-utility.sh tune –d

using the CLI short flag.

You can create a gesture by extending the AbstractGesture class from the OIG Gesture framework, and operations for that gesture by extending AbstractGestureOperation. The tune sample gesture implementation is included with OIG Configuration Utility in the TuningGesture.java source file. See Adding a Gesture for more information about creating gestures.

To use a gesture that you create, copy your gesture jar file to the lib directory, and add your gesture to the gesturesConfig section of oig-utility-config.json. Provided the gesture is valid, it's shown as an available gesture the next time you launch the utility.

The operations defined by these gestures can update the WebLogic Server configuration by applying the values from oig-configuration-attributes.json to the system.

Reports

When you perform one or more operations using OIG Configuration Utility in interactive mode, before any changes are made to the system, the utility produces a report showing the initial and final attribute values.

In both interactive and silent modes, you can direct the utility to produce a pre-execution report for the gesture operations you pass to the utility. This will produce a report with the initial and final attribute values, based on the operations that you selected. No changes will be made to the system.

To create a pre-report, use the –r or –report options. For example, in silent mode, you might want a pre-report for the tune database operation, in which case you'd call the utility similar to:

./oig-config-utility.sh –S –rpt tune –d [inputs]

Whether generated automatically in interactive mode, or explicitly using the –r or -report options, reports are stored in the reports/ directory by default. The reports are in HTML and can be viewed in any web browser.