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.
Parent topic: Using OIG Configuration Utility
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!
Parent topic: Interactive Mode and Silent Mode
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
Parent topic: Interactive Mode and Silent Mode
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 thebackup/
,baseline/
, andcurrent_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.
Parent topic: Using OIG Configuration Utility
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.
Parent topic: Baselines and Restoration
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.
Parent topic: Baselines and Restoration
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.
Parent topic: Using OIG Configuration Utility
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.
Parent topic: Using OIG Configuration Utility