AutoUpgrade Command-Line Parameters and Options
Review the AutoUpgrade parameters and select the parameters and options for your Oracle Database upgrade use case.
Use the parameters with the command java -jar autoupgrade.jar
.
- AutoUpgrade Command-Line Syntax
To see how to use AutoUpgrade to perform your upgrades, review the syntax and run time use cases. - auto_config
The AutoUpgrade parameterauto_config
automatically generates a configuration file for upgrading a database, and enables you to to run different AutoUpgtrade modes using that configuration file. - debug
The AutoUpgrade parameterdebug
turns on the AutoUpgrade debug message feature, which assists you with correcting faulty AutoUpgrade job syntax. - clear_recovery_data
The AutoUpgrade parameterclear_recovery_data
removes the recovery checkpoint, which causes AutoUpgrade to have a fresh start the next time the tool is launched on specified databases, or on all databases. - config
The AutoUpgrade parameterconfig
identifies the configuration file that you use to provide information about databases that you want to upgrade. - config_values
The AutoUpgrade parameterconfig_values
enables you to provide the same input values about systems as a text configuration file. You can use it conjunction with theconfig
parameter. - console
The AutoUpgrade parameterconsole
turns on the AutoUpgrade console, and provides a set of commands to monitor the progress of AutoUpgrade jobs. - create_sample_file
The AutoUpgrade parametercreate_sample_file
generates either a configuration file, or a settings file. You edit these files to create production configuration or settings files for AutoUpgrade. - error_code
The AutoUpgrade parametererror_code
shows the error codes for AutoUpgrade errors. - listchecks
The AutoUpgrade parameterlistchecks
either provides a list of all upgrade checks for an upgrade, or if you specify a particular check, the details about the check you specify. - before_action
(Optional) Indeploy
mode, specifies a custom action that you want to have performed before starting the upgrade job for the specific database job addressed by the prefix. If you want to have a script run before all upgrade jobs, then specify that script by using the local parameter (global.before_action) - before_action
(Optional) Specifies a custom user script that you want to have run for all upgrades before starting the upgrade jobs. - before_action.create_home
(Optional for AutoUpgrade patching) Increate_home
mode, specifies a custom action that you want to have performed before starting the patchcreate_home
mode for the specific database job addressed by the prefix. - before_action.deploy
(Optional for AutoUpgrade patching). Indeploy
mode, specifies a custom action that you want to have performed before starting the upgrade job for the specific database job addressed by the prefix. - catctl_options
(Optional for AutoUpgrade upgrades) Specifies one or more of a set ofcatctl.pl
options that you can select for AutoUpgrade to submit forcatctl.pl
to override default behavior. - checklist
(Optional) Specifies the path to a checklist that you can use to override the default list of fixups that AutoUpgrade performs, such as fixups that you do not want implemented automatically, due to policy or security concerns. - close_source
(Optional for AutoUpgrade upgrades) Closes the source non-CDB or source PDB just before AutoUpgrade starts a non-CDB to PDB conversion, starts an unplug-relocate upgrade, or uses a refreshable clone PDB. - Common Parameters for the AutoUpgrade Configuration File (Upgrade and Patch)
You can use common parameters for the AutoUpgrade configuration file (config) with bothupgrade
and software maintenance-patch
operations. - create_listener
(Optional) Creates a listener in the new Oracle home after an upgrade. - defer_standby_log_shipping
(Optional for AutoUpgrade upgrades) Defers shipping logs from the primary database to any standby database. All log archive destionations (log_archive_dest_n
) are set to deferred. - del_after_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of aPFILE
whose parameters you want to have removed after upgrade. - del_after_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of aPFILE
whose parameters you want to have removed after thePFILE
upgrade. - del_during_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of a PFILE whose parameters you want to have removed during upgrade. - del_during_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of aPFILE
whose parameters you want to have removed during thePFILE
upgrade. - delete_wincredential_file
(Optional) Deletes the Microsoft Windows credential object file when the AutoUpgrade job is complete. - dictionary_stats_after
(Optional) Specifies that AutoUpgrade gathers data dictionary statistics on the target database after the upgrade is complete. - dictionary_stats_before
(Optional) Specifies that AutoUpgrade gathers data dictionary statistics on the source database before starting the upgrade. - download
(Optional for AutoUpgrade patching) Specifies whether to automatically download patches from My Oracle Support. . - drop_db_link
(Optional for AutoUpgrade upgrades) Specifies that the database link set up for an unplug-plug relocate (hot clone) upgrade is dropped after successful job completion. - drop_grp_after_patching
(Optional for AutoUpgrade patching) Deletes the Guaranteed Restore Point (GRP) after database patch maintenance. - drop_grp_after_upgrade
(Optional for AutoUpgrade upgrades) Deletes the Guaranteed Restore Point (GRP) after database upgrade. - drop_win_src_service
(Optional for upgrades only) For upgrades on Microsoft Windows, specifies whether to drop the Windows operating system service for the source Oracle Database after upgrade. - em_blackout_suffix
(Optional) Enables you to specify a suffix to add to the default autoupgrade blackout - em_target_name
(Optional) Enables you to specify that the database that you name is monitored by Enterprise Manager so the monitoring can be updated to the new Oracle home. - emcli_path
(Optional) Enables you to specify the path to the Enterprise Manager Command Line Interface (EMCLI) command. - enable_local_undo
(Optional for AutoUpgrade upgrades) For a CDB upgrade, specifies whether or notLOCAL
undo should be enabled before the upgrade ofCDB$ROOT
. - env
(Optional) Specifies custom operating system environment variables set on your operating system, excludingORACLE_SID
,ORACLE_HOME
,ORACLE_BASE
, andTNS_ADMIN
. - exclusion_list
(Optional for AutoUpgrade upgrades) Sets a list of PDBs that you want to be excluded from the AutoUpgrade run. This parameter only applies to the multitenant architecture (CDB) databases. If you are plugging in and upgrading a non-CDB database, then this parameter is ignored. - export_rman_backup_for_noncdb_to_pdb
(Optional for AutoUpgrade upgrades) Specifies that AutoUpgrade transports metadata from the source non-CDB database to the target PDB database as part of the conversion process. - fixed_stats_before
(Optional) Specifies that AutoUpgrade gathers fixed object statistics on the source database before starting the upgrade. - folder
(Required for AutoUpgrade patching) Specifies the directory that contains the patch zip files as well as any Oracle Database base images that are required. - Global Common Parameters for the AutoUpgrade Config File
The Common global parameters for the AutoUpgrade configuration file (config) enable you to set a global parameter for both software maintenance (-patch
) and upgrade (upgrade
). - Global Patch Parameters for the AutoUpgrade Config File
The patch global parameters for the AutoUpgrade configuration file (config) enable you to set a global parameter for software maintenance (-patch
). - Global Upgrade Parameters for the AutoUpgrade Config File
The upgrade global parameters for the AutoUpgrade configuration file (config) enable you to set a global parameter for upgrades (upgrade
). - global_log_dir
(Optional) Sets the location of the AutoUpgrade log files, and temporary files that belong to global modules, which AutoUpgrade uses. - home_settings.account_type
(Optional) for AutoUpgrade patching) On Microsoft Windows, this option specifies the type of account to use when creating the target ORACLE_HOME. - home_settings.binopt.asm
(Optiona for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for Oracle ASM (asm
) turned ON or OFF. - home_settings.binopt.dm
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for Oracle Data Mining (dm
) turned ON or OFF. - home_settings.binopt.jox
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for the JavaVM JIT Compiler (jox) turned ON or OFF. - home_settings.binopt.olap
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for the On Line Application Processing (OLAP) options (olap
) turned ON or OFF. - home_settings.binopt.part
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for Oracle Partitioning (part
) turned ON or OFF. - home_settings.binopt.rac
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for Oracle RAC (rac
) turned ON or OFF. - home_settings.binopt.rat
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for Oracle Real Application Testing (rat
) turned ON or OFF. - home_settings.binopt.sdo
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for Oracle Spatial Data Option Messages (sdo
) turned ON or OFF. - home_settings.binopt.uniaud
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for Oracle's unified auditing feature (uniaud
) turned ON or OFF. - home_settings.cluster_nodes
(Optional for AutoUpgrade patching) Specifies the list of nodes in an Oracle Real Applications (Oracle RAC) cluster on which you want to run AutoUpgrade patching. - home_settings.edition
(Optional for AutoUpgrade patching) Specifies the Oracle Database edition that you want to use for creating the target ORACLE_HOME. - home_settings.home_name
(Optional for AutoUpgrade patching) Specifies the Oracle home name that will be used for the database in theinventory.xml
file in the Oracle Inventory (oraInventory) directory when creating the target ORACLE_HOME. - home_settings.ignore_opatch_conflict
(Optional for AutoUpgrade patching) Specifies the conflict resolution strategy for resolving conflicts between patches caused by one-off patches. - home_settings.ignore_prereq_failure
(Optional for AutoUpgrade patching) Specifies whether AutoUpgrade patching ignores any prerequisite check errors that occur during installation on an Oracle Real Application Clusters (Oracle RAC) target home. - home_settings.inventory_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the Oracle Inventory group (OINSTALL). - home_settings.inventory_location
(Optional for AutoUpgrade patching) Specifies the directory that should be used for the Oracle Database inventory (oraInventory
) directory. - home_settings.oracle_base
(Optional for AutoUpgrade patching) Specifies the directory that should be used for the Oracle base directory. - home_settings.osbackupdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system OSBACKUPDBA backup and recovery system privileges group for an Oracle Database. - home_settings.dba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system DBA system privileges group (OSDBA) management for the database. - home_settings.osdgdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system OSDGDBA system privileges to administer and monitor Oracle Data Guard. - home_settings.oskmdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system SYSKM system privileges for encryption key management for applications such as Oracle Wallet Manager. - home_settings.oper_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system operator (OSOPER) system privileges group. - home_settings.osracdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system SYSRAC privileges to perform day to day administration of Oracle Database on an Oracle RAC cluster. - home_settings.read_only
(Optional for AutoUpgrade patching) Specifies whether a Read-Only Oracle home should be enabled when creating the target ORACLE_HOME. - home_settings.ru_apply
(Optional for AutoUpgrade patching) Specifies whether a release update (RU) is installed at the same time as theORACLE_HOME
, or installed as a separate step by OPatch. - Ignore Fixups and Checks Using the AutoUpgrade Configuration File
To skip an entire check and fixup step for a database, you can direct AutoUpgrade to read the fixuprunfix
flag from the fixups checklist file, and set the flag for that fixup fromYES
toSKIP
. - ignore_errors
(Optional for AutoUpgrade upgrades) Enables you to specify a comma-delimited list of specific Oracle errors that you want AutoUpgrade to ignore during the upgrade or patching process. - json_progress_writing_interval
(Optional) Sets the time interval for how often to write the AutoUpgrade progress JSON report. - keep_pdb_save_state
(Optional for AutoUpgrade upgrades) Specifies that if the PDB has a saved state in the source CDB, then you can either save or not save the PDB state on the target CDB. - keep_source_pdb
(Optional for AutoUpgrade upgrades) Specifies if the source PDB in an unplug-plug upgrade operation is kept in a closed state instead of being removed from the source CDB. - keystore
(Optional) Specifies the location for a dedicated software keystore used exclusively by AutoUpgrade to store passwords, and other sensitive information. - Local Common Parameters for the AutoUpgrade Config File
The common Local parameters enable you to configure AutoUpgrade processing in the configuration file (config) for specific Oracle Databases either for software maintenance (-patch
) or upgrade (upgrade
). - Local Configuration File Parameter Fixups Checklist Example
To include or exclude specific fixups for individual databases during upgrades, use the local configuration file checklist. - Local Patch Parameters for the AutoUpgrade Config File
The patch parameters enable you to configure AutoUpgrade processing in the configuration file (config) for specific Oracle Databases for software maintenance (-patch
). - Local Upgrade Parameters for the AutoUpgrade Config File
The upgrade local parameters enable you to configure AutoUpgrade processing in the configuration file (config) for specific Oracle Databases for upgrades (upgrade
). - Locally Modifiable Global Common Parameters for the AutoUpgrade Configuration File
The Common locally modifiable global parameters for the AutoUpgrade configuration file enable you to set modifiable global parameters in the configuration (config) file that can be overwritten by a database-specific local parameter. - revert_after_action.deploy
(Optional for AutoUpgrade patching) Indeploy
mode, specifies a custom action that you want to have run on the operating system after a system restoration is completed for the specific database job addressed by the prefix. - revert_before_action
(Optional) Specifies a custom action that you want to have run on the operating system before a system restoration is completed for the specific database job addressed by the prefix, and the database is up. - revert_before_action.create_home
(Optional for AutoUpgrade patching) Increate_home
mode, specifies a custom action that you want to have run on the operating system after a system restoration is completed for the specific database job addressed by the prefix. - revert_before_action.deploy
(Optional for AutoUpgrade patching). Indeploy
mode, specifies a custom script to revert an action before starting the upgrade job for the specific database job addressed by the prefix. - rman_catalog_connect_string
(Optional) Specifies the RMAN connection string used to connect to an RMAN database. - run_dictionary_health
(Optional for AutoUpgrade upgrades) Specifies whether you run Oracle Dictionary Health Checks as part of preupgrade checks to identify database dictionary inconsistencies. - run_utlrp
(Optional) Enables or disables running a version ofutlrp.sql
as part of post upgrade, to recompile only invalid objects in Oracle-maintained schemas. - sid
(Required) Identifies the Oracle system identifier (SID) of the database that you want to upgrade. - skip_tde_key_import
(Optional for AutoUpgrade upgrades) When set toyes
, the upgrade is run, but import of the source database KeyStore into the target database is skipped, without raising an error. - target_is_remote
(Optional for AutoUpgrade upgrades) Specifies whether the target CDB is located on the same system as the cloned PDB. - load_password
The AutoUpgrade parameterload_password
enables you to enter passwords safely into AutoUpgrade's keystore. - load_win_credential
The AutoUpgrade parameterload_win_credential
uses PowerShell to create a credential object so that AutoUpgrade can be run without interruption during the upgrade. - mode
The AutoUpgrade parametermode
value sets the mode from which AutoUpgrade runs. - noconsole
The AutoUpgrade parameternoconsole
turns off the AutoUpgrade console, so that AutoUpgrade runs using only configuration file information. - Patch
The AutoUpgrade parameterpatch
is used to specify that AutoUpgrade is performing a patch operation, and not an upgrade operation. - preupgrade
The AutoUpgrade parameterpreupgrade
runs database checks and preupgrade fixups that fix most issues before you start an upgrade, and postupgrade fixups that fix most issues after an upgrade is completed. - settings
The AutoUpgrade parametersettings
identifies the configuration file that you use to provide custom runtime configuration of the AutoUpgrade utility. - version
The AutoUpgrade parameterversion
prints to the terminal screen the current build of theautoupgrade.jar
file. - restore
The AutoUpgrade parameterrestore
performs a system-level restoration of the AutoUpgrade jobs that you specify. - restore_on_fail
The AutoUpgrade parameterrestore_on_fail
automatically restores any job that failed during the deployment. - zip
The AutoUpgrade parameterzip
creates a zip file of log files required for filing an AutoUpgrade service request.
Parent topic: Using AutoUpgrade for Oracle Database Upgrades
AutoUpgrade Command-Line Syntax
To see how to use AutoUpgrade to perform your upgrades, review the syntax and run time use cases.
Prerequisites
-
AutoUpgrade is compatible with JDK 8 to JDK 11. You must have at least Java Development Kit (JDK) 8 or a later JDK release installed in your source environment.
JDK 8 is installed with every release starting with Oracle Database 12c Release 2 (12.2). For any release earlier than 12.2, you must either run AutoUpgrade using the Java release in the target Oracle Database, or you must install JDK 8 on your source database server.
Starting with Oracle Database 23ai, every Oracle home includes Java Runtime Environment (JRE) 11. AutoUpgrade is compiled with Java 11, and is compatible with JDK 8 to JDK 11.
-
Oracle Database upgrades using the AutoUpgrade utility follow the same upgrade rules that apply to manual Oracle Database upgrades. Confirm that your source Oracle Database release is supported for upgrade.
With non-CDB to PDB conversion and upgrade, AutoUpgrade can automatically complete both upgrade and conversion when these conditions are met:
- The target release CDB must exist.
- In the AutoUpgrade configuration file, where the target CDB system
identifier is
target_cdb
, you must set the local parametertarget_cdb
using the following syntax:target_cdb=target_cdb
. For example:target_cdb=cdb1
- The
target_cdb
value is the Oracle SID of the CDB into which you are plugging the non-CDB.
File Path
The AutoUpgrade utility is a Java JAR file that is located in the new release Oracle Database home.
Oracle_home/rdbms/admin/autoupgrade.jar
Oracle strongly recommends that you obtain the latest AutoUpgrade JAR file from My Oracle Support. The JAR file and deployment instructions for the JAR file are available from My Oracle Support note 2485457.1
Syntax
AutoUpgrade command syntax is case-sensitive. Enter commands in lowercase.
java -jar autoupgrade.jar [options]
Multiple options can be concatenated.
Run Type One (Basic) Parameters for AutoUpgrade
Run type one (Basic) parameters and options for AutoUpgrade provide a starting point for preparing for upgrades.
Parameter | Description |
---|---|
-version |
Displays the AutoUpgrade version. |
-help |
Displays the help file for AutoUpgrade syntax. |
-create_sample_file [settings | config
config-file-name] |
Creates an example configuration file for AutoUpgrade. For a
description of the options, see the
|
Run Type Two (Core) Parameters for AutoUpgrade
Run type two (Core) parameters and options for AutoUpgrade provide essential upgrade functionality for most upgrade scenarios.
Parameter | Description |
---|---|
|
Identifies the configuration file that you use to provide
information about databases that you want to upgrade. For a
description of the options, see the |
|
Sets the mode from which AutoUpgrade runs. For a description of
the options, see the |
-restore -jobs
job# |
Performs a system-level restoration of the AutoUpgrade jobs that you specify |
|
If set, then when a job fails, the database is
restored automatically. Errors in PDBs are not considered
irrecoverable, only errors in |
|
Starts AutoUpgrade with the console enabled. |
|
Starts AutoUpgrade with the console disabled. |
-proceed |
Alters the predefined
-proceed
parameter topic.
|
|
Enables debug messages. |
|
Removes the recovery information, which causes AutoUpgrade to
start from the beginning on all databases, or on databases in a
comma-delimited list specified by |
|
Runs a system-level restoration of the specified jobs. The
databases are flashed back to the Guaranteed Restore Point
(GRP). Before you run this command, the GRP must already be
created by AutoUpgrade. For a full description of the options,
see the |
|
automatically restores any job that failed during the deployment. |
|
Zips up log files required for filing an AutoUpgrade service
request. For a description of the options, see the
|
Run Type Three (Additional) Parameters for AutoUpgrade
Run type three (Additional) parameters and options for AutoUpgrade are useful for particular upgrade scenarios, such as restarting from a failed point in an upgrade, or running particular fixups.
Parameter | Description |
---|---|
|
Enables debug messages. |
-error_code |
Displays the AutoUpgrade error codes. |
|
Displays the help file for AutoUpgrade syntax. |
|
Sets the mode from which AutoUpgrade runs. For a
description of the options, see the |
|
Provides a list of all upgrade checks for an upgrade, or if you specify a particular check, the details about the check you specify. |
|
Enables you to enter passwords AutoUpgrade requires safely into AutoUpgrade's keystore. |
|
Uses PowerShell to create a credential object so that AutoUpgrade can be run without interruption during the upgrade. |
|
Specifies that AutoUpgrade is performing a patch operation, and not an upgrade operation. |
|
Runs database checks and preupgrade fixups that fix
most issues before you start an upgrade, and postupgrade fixups
that fix most issues after an upgrade is completed. For a
description of the options, see the |
-settings |
Identifies the configuration file that you use to provide custom runtime configuration of the AutoUpgrade utility. |
auto_config
The AutoUpgrade parameter auto_config
automatically
generates a configuration file for upgrading a database, and enables you to to run different
AutoUpgtrade modes using that configuration file.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
System identifer options:
[ Mode options:
[ |
Default value |
There are no default values for the syntax input. Generated Configuration File: When running
If the primary location is read-only or inaccessible, then
AutoUpgrade attempts to generate the
At the time of this release, it is not possible to specify a custom
path for |
Usage Notes
The purpose of the auto_config
parameter is to simplify the database
upgrade process. When you run AutoUpgrade with this parameter, and no
auto_config.cfg
file exists, AutoUpgrade automatically
discovers and leverages existing system resources to generate a configuration file
for you. After you generate the auto_config.cfg
file, you can use
this parameter to specify which AutoUpgrade mode you want to run using the
information in the existing auto_config.cfg
file.
To use auto_config
, you must at least provide a valid system
identifier (SID) of the Oracle Database that you want to upgrade. You can specify
the SID using the -sid
option followed by the valid SID (for
example, -sid myCDBAI
) or by using the ORACLE_SID environment
variable in your operating system.
When an existing auto_config.cfg file does not exist, and you specify your database
and run AutoUpgrade with auto_config -sid
, AutoUpgrade extracts the
necessary information for the upgrade from your existing database, including the
current Oracle home and other relevant details. AutoUpgrade then identifies a valid
later release Oracle home that can be the upgade target release. AutoUpgrade then
generates a configuration file named auto_config.cfg
in a
convenient location (in the same location or in a nearby fallback location if the
primary location is read-only or inaccessible.
Examples
The following is an example of running the auto_config
parameter
where $ORACLE_SID is an environment variable in the current operative system,
followed by expected output:
java -jar autoupgrade.jar -auto_config
Created sample configuration file /home/oracle/auto_config.cfg
In the following example, AutoUpgrade generates an auto_config.cfg
file for the database identified by the SID myCDBAI
, followed by
expected output:
autoupgrade.jar -auto_config -sid myCDBAI
Created sample configuration file /home/oracle/auto_config.cfg
In the following example, AutoUpgrade run with auto_config -sid
$ORACLE_SID
generates an auto_config.cfg
file for the
earlier release specified by the environment variable $ORACLE_SID
,
and uses that file to run AutoUpgrade in analyze mode.
autoupgrade.jar -auto_config -sid $ORACLE_SID -mode analyze
Expected output:
Created sample configuration file /home/oracle/auto_config.cfg
AutoUpgrade XX.X.XXXXXX launched with default internal options
Processing config file ...
Pluggable database PDBX in myCDBAI is MOUNTED and it will not be processed
+--------------------------------+
| Starting AutoUpgrade execution |
+--------------------------------+
1 CDB(s) plus 1 PDB(s) will be analyzed
Type 'help' to list console commands
upg> Job 100 completed
.
.
.
------------------- Final Summary --------------------
Number of databases [ 1 ]
Jobs finished [1]
Jobs failed [0]
Please check the summary report at:
/home/oracle/autoConfig/cfgtoollogs/upgrade/auto/status/status.html
/home/oracle/autoConfig/cfgtoollogs/upgrade/auto/status/status.log
Parent topic: AutoUpgrade Command-Line Parameters and Options
debug
The AutoUpgrade parameter debug
turns on the AutoUpgrade
debug message feature, which assists you with correcting faulty
AutoUpgrade job syntax.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
|
Description
The AutoUpgrade debug
parameter turns on debugging messages, which
can assist you with correcting AutoUpgrade command syntax.
Usage Notes
Use the debug
parameter in concert with any other
AutoUpgrade parameter.
Parent topic: AutoUpgrade Command-Line Parameters and Options
clear_recovery_data
The AutoUpgrade parameter clear_recovery_data
removes the
recovery checkpoint, which causes AutoUpgrade to have a fresh start the next time the tool
is launched on specified databases, or on all databases.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
where:
|
Description
The AutoUpgrade clear_recovery_data
parameter removes the recovery
information, which causes AutoUpgrade to start from the beginning on specified databases, or
on all databases.
Usage Notes
Use after manually restoring a database and attempting a new upgrade. If
no list of jobs is provided, then by default, all job metadata is removed. Removing the
metadata does not remove log files, or reset the job identifier (jobid
)
counter. Only the AutoUpgrade files used to keep track of the progress of each job are
removed.
Examples
The following
example shows how to use the clear_recovery_data
option after you encounter
an issue, fix it, and then run AutoUpgrade again.
You start AutoUpgrade in deploy mode
java -jar autoupgrade.jar -config config.cfg -mode deploy
However, you encounter an issue during the upgrade. You stop AutoUpgrade, restore the database, and make changes to the database to correct the issue. To start over the AutoUpgrade procedure and clear out the current job state information, specify the job number that is associated with the previously run job. If you specify the job number, then AutoUpgrade only removes the state information for that specific job. The rest of the jobs will remain untouched.
java -jar autoupgrade.jar -config config.cfg -mode analyze -clear_recovery_data -jobs 100
Note:
The job ID number associates the job with the database. If you enter the wrong job id, then that causes AutoUpgrade to restart the wrong job from the beginning.
The analyze results are good, so you then run the deploy option again:
java -jar autoupgrade.jar -config config.cfg -mode deploy
When
you run autoupgrade.jar -config
with the
-clear_recovery_data
parameter, AutoUpgrade only drops state files. It
ignores any previously generated log files, so you can retain log files for further reference.
Running AutoUpgrade with the -clear_recovery_data
parameter also preserves
the latest jobid
information, so that the jobid
AutoUpgrade
creates for the next job is the next ID in sequence. By maintaining the jobid
state, AutoUpgrade helps you to avoid mixing log output from earlier AutoUpgrade jobs in the
same log file.
The following are additional examples of how you can run the
clear_recovery_data
parameter.
java -jar autoupgrade.jar -config config.cfg -clear_recovery_data java -jar autoupgrade.jar -config config.cfg -clear_recovery_data -jobs 111,222
Parent topic: AutoUpgrade Command-Line Parameters and Options
config
The AutoUpgrade parameter config
identifies the configuration file that you use to provide information about databases that you want to upgrade.
Property | Description |
---|---|
Parameter type | string |
Syntax |
|
Default value | None |
Description
The config
parameter specifies a configuration file name. It takes
three arguments:
-
The configuration file name
-
(Optional) The path to the configuration file, as represented by
config-file
When used in conjunction with the parameter
-load_password
, AutoUpgrade also creates a keystore for Transparent Data Encryption (TDE) passwords in the location specified by the global configuration file parameterglobal.keystore
, if that parameter is set in the configuration file for a database.
Examples
Running AutoUpgrade with a configuration file named myconfig.cfg
,
with the processing mode deploy
:
java -jar autoupgrade.jar -config myconfig.cfg -mode deploy
Parent topic: AutoUpgrade Command-Line Parameters and Options
config_values
The AutoUpgrade parameter config_values
enables you to
provide the same input values about systems as a text configuration file. You can use it
conjunction with the config
parameter.
Property | Description |
---|---|
Parameter type | String. |
Syntax |
-config_values [config-parameter1=value*,
|
Default value | None. |
Description
The config_values
parameter enables you to provide
values about database paths, instances, and target releases through the AutoUpgrade
command line that otherwise require you to specify a configuration file. AutoUpgrade
then creates a configuration file as the utility runs. Using
config_values
enables you to run AutoUpgrade without a
configuration file.
The config_values
options are a comma-delimited list
that can support multiple database upgrades. Each database configuration is
separated by asterisks (*) to identify different databases. Global entries must
include the global prefix in the name. For example:
global.autoupg_log_dir=/u01/app/oracle/cfgtoollogs/upgradelogs/
Local entries only need to include the name:
target_home=/u01/app/oracle/product/21.0.0.0/dbhome_1
Logging directories are resolved in the following manner.
-
Case: Global
autoupg_log_dir
is not specified.If the
config_file
parameter is not passed to AutoUpgrade, then the local directory is used as the global log directory. If theconfig_file
parameter is not passed to AutoUpgrade, then the global log directory defaults to the Java temporary directory:- Unix and Linux systems:
/tmp/autoupgrade
- Microsoft Windows:
C:\Users\name\AppData\Local\Temp\autoupgrade
- A configuration file is created with the name
autoupgradeYYYYMMMHHMMSS.cfg
, whereYYYY
is year,MMM
is month,HH
is hour,MM
is minute, andSS
is second.
- Unix and Linux systems:
-
Case:
Global autoupg_log_dir
is specified.If the
config_file
parameter does not pass the directory to AutoUpgrade, then AutoUpgrade creates a configuration file in the AutoUpgrade log directory specified by the parameter. If theconfig_file
parameter does not pass the directory to AutoUpgrade, then the configuration file is created under the global log directory. If you specify a configuration file name that already exists, then AutoUpgrade renames the existing configuration file using the suffixYYYYMMMHHMMMMSS.cfg
, whereYYYY
is year,MMM
is month,HH
is hour,MM
is minute, andSS
is second. For example: on April 29, 2020, at 08:30:04, if configuration file\tmp\autoupgrade.cfg
already exists, and you pass the file name-config_file \tmp\autoupgrade.cfg
to AutoUpgrade, then the existing file is renamed to\tmp\autoupgrade.cfg20200429083004
. AutoUpgrade then creates the new configuration file\tmp\autoupgrade.cfg
.
If you use the -config_values
parameter, and the user
account running the AutoUpgrade command has the following operating system
environment variables set, then AutoUpgrade picks up the path defined for these
variables:
ORACLE_HOME
- The Oracle home path for the source Oracle homeORACLE_TARGET_HOME
- The target Oracle home path.- Linux and Unix: Equivalent to an
export ORACLE_TARGET_HOME
command. For example:export ORACLE_TARGET_HOME=/u01/app/oracle/product/19.0.0/
- Microsoft Windows: Equivalent to a
SET ORACLE_TARGET_HOME
command. For example:SET ORACLE_TARGET_HOME=C:\oracle\19
- Linux and Unix: Equivalent to an
ORACLE_SID
- The Oracle Database system identifier (SID).- Linux and Unix: Set with the operating system shell command
export ORACLE_SID
. For example:export ORACLE_SID=sales
- Microsoft Windows: Set with the operating system shell
command
SET ORACLE_SID
command. For example:SET ORACLE_SID=sales
- Linux and Unix: Set with the operating system shell command
ORACLE_TARGET_VERSION
- The target release of the new Oracle home. You must set this operating system environment variable either when the target Oracle home does not exist, or the target home is a release earlier than Oracle Database 18c.-
Linux and Unix: Set with
export ORACLE_TARGET_VERSION
. For example, for Oracle Database 19c:export ORACLE_TARGET_VERSION=19.1
For Oracle Database 21c:
export ORACLE_TARGET_VERSION=21.1
-
Microsoft Windows: Set with
SET ORACLE_TARGET_VERSION
.For example, for Oracle Database 19c:
SET ORACLE_TARGET_VERSION=19.1
For example, for Oracle Database 21c:
SET ORACLE_TARGET_VERSION=21.1
If you use the
config_values
parameter in place of a configuration file, and you do not have these operating system environment variables set for the user account running AutoUpgrade, then you must provide at least these four values as arguments usingconfig_values
.-
Example: Running AutoUpgrade With an Existing Configuration File
Scenario: Running AutoUpgrade with an existing configuration file, using
config_values
. The following command syntax creates the
global.autoupg_log_dir
from the local directory where the
myconfig.cfg
file is created. As a result of this command, the
location for global.autoupg_log_dir
is set to
/dir
:
java –jar autoupgrade.jar –config /dir/myconfig.cfg –config_values
“source_home=/srcdir, target_home=/trgdir, sid=sales” –mode
deploy
The configuration file myconfig
is created in the path
/dir
, with the following entries:
global.autoupg_log_dir=/dir
autoupgrade1.source_home=/srcdir
autoupgrade1.target_home=/trgdir
autoupgrade1.sid=sales
Example: Running AutoUpgrade
Without Specifying a Value for –config_values
In analyze, fixup, upgrade, or deploy mode, if you have set user
environment values that AutoUpgrade requires to run, and you do not pass these
values as an argument for –config_values
, then AutoUpgrade defaults
to using the user environmental variables set on the server.
To understand how this works, suppose you run AutoUpgrade as the user
oracle
, for which the following environment variables are set,
where the target version is Oracle Database 21c:
ORACLE_HOME
is set to/u01/app/oracle/product/12.2.0.1/dbhome_1
ORACLE_TARGET_HOME
is set to/u01/app/oracle/product/19.0.0/dbhome_1
ORACLE_SID
is set tosales
ORACLE_TARGET_VERSION
is set to19.1
Now suppose you run the following command at 11:45:15 AM on September 30, 2020:
[Wed Sep 30 11:45:15] oracle@example:~$ java –jar autoupgrade.jar –config_values –mode analyze
Because the log directory was unspecified, AutoUpgrade defaults writing
the configuration file for the run to the temporary directory. The configuration
file AutoUpgrade creates resides in the path /tmp/autoupgrade
as
the file/tmp/autoupgrade/autoupgrade20200501114515.cfg
, with the
following entries:
global.autoupg_log_dir=/tmp/autoupgrade
# Value from environmental variable ORACLE_HOME
autoupgrade1.source_home=/u02/app/oracle/122
# Value from environmental variable ORACLE_TARGET_HOME
autoupgrade1.target_home=/scratch/oracle/19
# Value from environmental variable ORACLE_SID
autoupgrade1.sid=sales
# Value from environmental variable ORACLE_TARGET_VERSION
autoupgrade1.target_version=19.3
This option enables you to use AutoUpgrade to handle a single database upgrade without requiring you to specify extensive details about the upgrade.
Example: Running AutoUpgrade with –config_values
entries for
multiple databases
In this scenario, you run AutoUpgrade with
–config_values
entries for multiple databases, using
*
to delimit values for each database, with a target release of
Oracle Database 21c:
java –jar autoupgrade.jar –config /tmp/auto.cfg –config_values "global.autoupg_log_dir=/scratch/upglogs,source_home=/scratch/122,target_home=/scratch/21,sid=sales,*,source_home=/scratch/18,target_home=/scratch/21,sid=employees"
The configuration file is created in the directory /tmp
as /tmp/auto.cfg
, with the following entries.
global.autoupg_log_dir=/scratch/upglogs
autoupgrade1.source_home=/scratch/19
autoupgrade1.target_home=/scratch/21
autoupgrade1.sid=sales
autoupgrade2.source_home=/scratch/19
autoupgrade2.target_home=/scratch/21
autoupgrade2.sid=employees
Parent topic: AutoUpgrade Command-Line Parameters and Options
console
The AutoUpgrade parameter console
turns on the AutoUpgrade
console, and provides a set of commands to monitor the progress of AutoUpgrade jobs.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
|
Description
To monitor upgrades, use the AutoUpgrade parameter
console
to run the Console, which monitors the status of
upgrade jobs.
The AutoUpgrade console starts by default with the AutoUpgrade command.
You can enable or disable the AutoUpgrade console using the options
-console
|-noconsole
When you use the -noconsole
option, AutoUpgrade runs
using only the settings in the configuration file, without requiring console input.
Use the noconsole
option when you want to create scripts for
AutoUpgrade, such as in cases where you want to analyze multiple databases. After
the AutoUpgrade jobs are finished, you can review the output of the Analyze mode
logs to see what is required to upgrade each of the databases included with your
configuration script.
You can use the proceed option to have AutoUpgrade start a job at a time that you specify. You have three options:
- Specify no start time (default: Delay start by one minute after the command is run)
- Specify a start time delay with an hour and minute value from the time the command is run
- Specify a start delay with a day, month, year, minute, and second delay value from the time the command is run
Note:
You can start as many instances of AutoUpgrade as you want, but each
instance must use a unique global logging directory
(global.autoupg_log_dir
). If you only have one global
logging directory, then you can only start one instance.
Usage Notes
When you start the console, you can use options within the console.
Console Option | Description |
---|---|
|
Closes and exits from the console. If there are jobs running, then they are stopped. |
|
Displays the console command help. |
|
Lists jobs by status, up to the number of jobs you specify with the numeric value
|
|
Displays the restoration queue. |
|
Displays the queue of jobs to stop. |
|
Enables you to alter the predefined
You must specify a job number by using the
The You can enter
|
|
Displays the tasks that are running. |
|
Clears the terminal display. |
|
Restarts from a previous job that was running,
specified by a numeric value (
|
|
Lists the status of a particular job with the response you specify with the flag. Flags:
|
|
Restores the database in the AutoUpgrade job
specified by the integer value When run with the |
|
Displays all log file locations. |
|
Stops the job specified by the numeric value that you provide ( |
-h[ist][/number]
|
Displays the console command-line history, and takes the option to run a command again, depending on the flat with which you run it: Flags:
|
Parent topic: AutoUpgrade Command-Line Parameters and Options
create_sample_file
The AutoUpgrade parameter create_sample_file
generates either a configuration file, or a settings file. You edit these files to create production configuration or settings files for AutoUpgrade.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
|
Default value |
For You can add a clause to specify the type of AutoUpgrade configuration file, using one of the following options:
When you add the |
Usage Notes
The create_sample_file
parameter is optional. It cannot be used together with other parameters. When you specify this parameter, it requires either the settings
or the config
clause:
settings
: Generates an AutoUpgrade settings file, either with the name sample_autoupg.cfg
,
or with a name that you specify.
config
: Generates an AutoUpgrade configuration file, either with the name
sample_config.cfg
, or with a name
that you specify.
After you generate one of these example files, you can modify the file to control how the AutoUpgrade utility performs upgrades.
-
config
: Generates a template upgrade configuration file of a configuration mode type. AutoUpgrade generates a file namedsample_config.cfg
, or with a name you provide, in the current folder -
settings
AutoUpgrade generates a file namedsample_autoupg.cfg
, or with the name you provide, in the current folder.
For both the config
and settings
options, the
default file name is generated with the extension .cfg
. However,
AutoUpgrade can read files without an extension, or with an extension that you
provide, as long as the file is a valid (plain text) file. The default extension is
for convenience in identifying these files as configuration files.
Generating an example configuration file is a standard part of preparing to use AutoUpgrade. After you customize the configuration file parameters in the example configuration file, you can use that file as the production settings and configuration file for your upgrade.
Caution:
The settings file is used to overwrite internal settings of the AutoUpgrade. Generating an example settings file is not required for most use cases. Use carefully.
Examples
Example of running the
create_sample_file
parameter with
the config
clause:
[oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file config
Created sample configuration file /home/oracle/sample_config.cfg
Example of running the
create_sample_file
parameter with
the config
, clause specifying an
output configuration file name:
[oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file config sales01
Created sample configuration file /home/oracle/sales01.cfg
Example of running the
create_sample_file
parameter with
the settings
clause:
oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file settings
Created sample settings file /home/oracle/sample_autoupg.cfg
Example of running the create_sample_file
parameter
with the settings
, clause specifying an output configuration file
name:
oracle@example ~]$ java -jar autoupgrade.jar -create_sample_file settings testsetting.test
Created sample settings file /home/oracle/testsetting.test
Parent topic: AutoUpgrade Command-Line Parameters and Options
error_code
The AutoUpgrade parameter error_code
shows the error codes
for AutoUpgrade errors.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
|
Default value |
When no error code is specified, all AutoUpgrade error codes are displayed in the Console. When an error code is specified, the information about the specified error code is displayed in the Console. |
Examples
When entered without a specification, Autoupgrade produces descriptions of all of the error codes:
$ java -jar autoupgrade.jar -error_code ERROR1000.ERROR = UPG-1000 ERROR1000.CAUSE = It was not possible to create the data file where the jobsTable is being written or there was a problem during the writing, it might be thrown due to a permission error or a busy resource scenario ERROR1001.ERROR = UPG-1001 ERROR1001.CAUSE = There was a problem reading the state file perhaps there was corruption writing the file and in the next write it might be fixed ERROR1002.ERROR = UPG-1002 ERROR1002.CAUSE = Error deserializing the object for rerun, review log for any errors . . .
When entered with a specific error code, AutoUpgrade provides output for the error that you specify. For example:
java -jar autoupgrade.jar -error_code UPG-3010
This command produces the following output:
ERROR3010.ERROR = UPG-3010 ERROR3010.CAUSE = Error running approot_to_pdb.sql script
Here is another example:
$ java -jar autoupgrade.jar -error_code UPG-1400
This command produces the following output:
ERROR1400.ERROR = UPG-1400 ERROR1400.CAUSE = Database upgrade failed with errors
Parent topic: AutoUpgrade Command-Line Parameters and Options
listchecks
listchecks
either
provides a list of all upgrade checks for an upgrade, or if you specify a particular
check, the details about the check you specify.
Property | Description |
---|---|
Parameter type | string |
Syntax |
|
Default value | None. If no specific check is specified, then a list of all AutoUpgrade checks is provided. |
Examples
When entered without a specification, the Autoupgrade
listchecks
parameter generates descriptions of all of the
checks AutoUpgrade performs for the upgrade.
$ java -jar autoupgrade.jar -listchecks
Check : AMD_EXISTS
Description : Starting with Oracle Database 12c, the OLAP Catalog (OLAP AMD) is desupported and will be automatically marked as OPTION OFF during the database upgra
de if present. Oracle recommends removing OLAP Catalog (OLAP AMD) before database upgrade. This step can be manually performed before the upgrade to reduce downtime.
Fixup Action : Remove OLAP Catalog by running the {1} SQL script $ORACLE_HOME/olap/admin/catnoamd.sql script.
Severity : WARNING
Fixup Stage : PRE
Min Version(inclusive) Check applies : NONE
Max Version(exclusive) Check applies : NONE
Check Introduced Version : NONE
Check Removed Version : NONE
Manual Fixup or Automatic : AUTO
AutoUpgrade Only : NO
Run for Datapatch : NO
Check : APEX_MANUAL_UPGRADE
Description : Starting with Oracle Database Release 18, APEX is not upgraded automatically as part of the database upgrade. Refer to My Oracle Support Note 1088970.
1 for information about APEX installation and upgrades. Refer to MOS Note 1344948.1 for the minimum APEX version supported for your target database release. Unsupported ver
sions of APEX will be in an INVALID state when its database dependencies are not in sync with the upgraded database.
Fixup Action : Upgrade Oracle Application Express (APEX) manually before or after the database upgrade.
Severity : WARNING
Fixup Stage : PRE
Min Version(inclusive) Check applies : NONE
Max Version(exclusive) Check applies : NONE
Check Introduced Version : 18
Check Removed Version : NONE
Manual Fixup or Automatic : MANUAL
AutoUpgrade Only : NO
Run for Datapatch : NO
Check : APEX_PATCH
Description : The APEX patching process is not performed by the {1} Oracle database upgrade. The APEX version upgrade only ensures that the APEX version is upgrade
d to version {3} and does not guarantee the version is brought all the way to the patched level {2}. If a PDB from this CDB is unplugged and plugged into another ROOT, the
.
.
.
When entered with a specified check, listchecks
provides details about the checks for the check you specify:
$ java -jar autoupgrade.jar -listchecks XDB_RESOURCE_TYPE
Check : XDB_RESOURCE_TYPE
Description : Direct access to either TYPE XDB.XDB$RESOURCE_T or TABLE XDB.XDB$RESOURCE is restricted to Oracle internal code only.
Fixup Action : Please contact Oracle Support to resolve the problem.
Severity : ERROR
Fixup Stage : PRE
Min Version(inclusive) Check applies : 11.1
Max Version(exclusive) Check applies : NONE
Check Introduced Version : NONE
Check Removed Version : NONE
Manual Fixup or Automatic : MANUAL
AutoUpgrade Only : NO
Run for Datapatch : NO
Related Topics
Parent topic: AutoUpgrade Command-Line Parameters and Options
before_action
(Optional) In deploy
mode, specifies a custom action that
you want to have performed before starting the upgrade job for the specific database job
addressed by the prefix. If you want to have a script run before all upgrade jobs, then
specify that script by using the local parameter (global.before_action)
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.The script that you use must be in the form of name.ext
(for example, myscript.sh
), so that AutoUpgrade can identify the
type of script that you want to run. Permitted extension options:
- Unix shell (
.sh
) - Microsoft Windows batch (
.bat
,.cmd
) - Microsoft Windows PowerShell (
.ps1
) - Oracle SQL file (
.sql)
, with a local operation only designated by the prefix.
Note:
Thebefore_action.deploy
parameter for AutoUpgrade patching and the
local parameter before_action
parameter cannot be specified in the
same configuration file.
By default, if the script fails, then AutoUpgrade continues to run. Use
the Y
flag to specify that AutoUpgrade stops if the operating
system detects that your script fails. If the script finishes with a status
different than 0
, then it is considered a failed completion.
In contrast to the global before_action
parameter, the
local before_action
parameter can specify a SQL script, which can
run on the database in the source database Oracle home, using the earlier release
Oracle Database binaries. The script runs on a non-CDB Oracle home, or on
CDB$ROOT
. If you want to run additional container-specific
actions, then they must be set within the code. For more complex scenarios, you can
run container-specific actions in a shell.
The output of the script is captured and stored in files. Both
stdout
and stderr
are captured. The files are
stored in the preupgrade
subdirectory in the directory matching the
specific database or job.
The following environment variables are set in the shell that runs the script:
ORACLE_SID
ORACLE_UNQNAME
ORACLE_BASE
ORACLE_HOME
TNS_ADMIN
Examples
Run the specified script before AutoUpgrade starts processing
deploy
mode, with the Y
flag set to stop
AutoUpgrade if the script fails:
sales.before_action=/user/path/script.sh Y
Run the specified script before AutoUpgrade starts processing, with AutoUpgrade set to continue to run if the script fails:
sales4.before_action=/user/path/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
before_action
(Optional) Specifies a custom user script that you want to have run for all upgrades before starting the upgrade jobs.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.The script that you use must be in the form of
name.ext
(for example,
myscript.sh
), so that AutoUpgrade can identify the
type of script that you want to run. If you want to have a script
run before a specific upgrade job, then specify that script by using
the local parameter (local.before_action
)
Permitted extension options:
-
Unix shell (
.sh
) -
Microsoft Windows batch (
.bat
,.cmd
) -
Microsoft Windows PowerShell (
.ps1
)
By default, if the script fails, then AutoUpgrade continues
to run. Use the Y
flag to specify that AutoUpgrade
stops if the operating system detects that your script fails. If the
script finishes with a status different than 0
,
then it is considered a failed completion.
The output of the script is captured and stored in files. Both
stdout
and stderr
are
captured. The files are stored in the preupgrade
subdirectory in the directory matching the specific database or job.
The following environment variables are set in the shell that runs the script:
ORACLE_SID
ORACLE_UNQNAME
ORACLE_BASE
ORACLE_HOME
TNS_ADMIN
Examples
If the script fails, then stop AutoUpgrade:
global.before_action=/path/to/my/script.sh Y
If the script fails, then continue AutoUpgrade:
global.before_action=/path/to/my/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
before_action.create_home
(Optional for AutoUpgrade patching) In create_home
mode,
specifies a custom action that you want to have performed before starting the patch
create_home
mode for the specific database job addressed by the
prefix.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.For patching operations, the local
before_action.create_home
can specify an actoin that you want
performed before creating a new Oracle home for the patched database using the
target Oracle Database binaries on a non-CDB Oracle home, or on CDB$ROOT. You must
specify the new Oracle home path.
The following environment variables are set in the shell that runs the script:
ORACLE_SID
ORACLE_UNQNAME
ORACLE_BASE
ORACLE_HOME
TNS_ADMIN
Syntax
prefix.before_action.create_home=/my/new/oracle/home/
Examples
Run the specified script before AutoUpgrade starts processing
create_home
mode, with the Y
flag set to stop
AutoUpgrade if the script fails:
sales.before_action.create_home=/user/path/script.sh Y
Run the specified script before AutoUpgrade starts processing
create_home
mode, with AutoUpgrade set to continue to run if
the script fails:
sales4.before_action.create_home=/user/path/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
before_action.deploy
(Optional for AutoUpgrade patching). In deploy
mode,
specifies a custom action that you want to have performed before starting the upgrade job
for the specific database job addressed by the prefix.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.The script that you use must be in the form of name.ext
(for example, myscript.sh
), so that AutoUpgrade can identify the
type of script that you want to run. Permitted extension options:
- Unix shell (
.sh
) - Microsoft Windows batch (
.bat
,.cmd
) - Microsoft Windows PowerShell (
.ps1
) - Oracle SQL file (
.sql)
, with a local operation only designated by the prefix.
Note:
Thebefore_action.deploy
parameter for AutoUpgrade patching and the
local parameter before_action
parameter cannot be specified in the
same configuration file.
By default, if the script fails, then AutoUpgrade continues to run. Use
the Y
flag to specify that AutoUpgrade stops if the operating
system detects that your script fails. If the script finishes with a status
different than 0
, then it is considered a failed completion.
For patching operations, the local before_action.deploy
parameter can specify a SQL script, which then runs on the database using the target
Oracle Database binaries on a non-CDB Oracle home, or on CDB$ROOT
.
If you want to run additional container-specific actions, then they must be set
within the code. For more complex scenarios, you can run container-specific actions
in a shell.
The output of the script is captured and stored in files. Both
stdout
and stderr
are captured. The files are
stored in the preupgrade
subdirectory in the directory matching the
specific database or job.
The following environment variables are set in the shell that runs the script:
ORACLE_SID
ORACLE_UNQNAME
ORACLE_BASE
ORACLE_HOME
TNS_ADMIN
Examples
Run the specified script before AutoUpgrade starts processing
deploy
mode, with the Y
flag set to stop
AutoUpgrade if the script fails:
sales.before_action.deploy=/user/path/script.sh Y
Run the specified script before AutoUpgrade starts processing
deploy
mode, with AutoUpgrade set to continue to run if the
script fails:
sales4.before_action.deploy=/user/path/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
catctl_options
(Optional for AutoUpgrade upgrades) Specifies one or more of a set of
catctl.pl
options that you can select for AutoUpgrade to submit for
catctl.pl
to override default behavior.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.
Available catctl.pl
options:
-n
Number of processes to use for parallel operations. For Replay upgrades, the number of parallel processes used for the upgrade defaults to the value of (CPU_COUNT
divided by 4) . For Classic upgrades, the default forCDB$ROOT
andNON-CDB
databases is 8.-N
Number of processors to use when upgrading PDBs. For Replay upgrades, the number of parallel processes used for the upgrade defaults to the value of (CPU_COUNT
divided by 4) For Classic upgrades, the default is 2-T
Takes offline user schema-based table spaces.-z
Turns on production debugging information forcatcon.pl
.
Examples
sales4.catctl_options=-n 24 -N 4
Related Topics
Parent topic: AutoUpgrade Command-Line Parameters and Options
checklist
(Optional) Specifies the path to a checklist that you can use to override the default list of fixups that AutoUpgrade performs, such as fixups that you do not want implemented automatically, due to policy or security concerns.
Usage Notes
To use this parameter during other AutoUpgrade modes, you must run
AutoUpgrade in analyze
mode. After AutoUpgrade finishes the
analysis, you can then find the checklist file identified by the database name under
the precheck directory (dbname_checklist.cfg
). Update the file manually to exclude
the fixups that you want AutoUpgrade to bypass, and save the file with a new name.
When you run AutoUpgrade again, you can specify the parameter pointing to the
checklist file that you created, and modify fixups that are performed for individual
databases. If you do not specify a checklist file path, then the set of fixups that
run during the upgrade is the latest version of the checklist file that is created
during the deploy mode that you specified.
Examples
sales.checklist=/u01/app/oracle/upgrade-jobs/salesdb_checklist.cfg
In the preceding example, salesdb_checklist.cfg
is the
checklist configuration file for the database salesdb
.
Parent topic: AutoUpgrade Command-Line Parameters and Options
close_source
(Optional for AutoUpgrade upgrades) Closes the source non-CDB or source PDB just before AutoUpgrade starts a non-CDB to PDB conversion, starts an unplug-relocate upgrade, or uses a refreshable clone PDB.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.During the operations described above, if close_source
is set to yes
(the default), then AutoUpgrade closes source non-CDB
or source PDB just before starting the upgrade. Additionally, if Oracle Real
Application Clusters or Oracle Grid Infrastructure (CRS) services are configured for
a non-CDB source, then they are disabled before starting the upgrade.
This parameter can only be used when the source and target databases are both on the same system. When they are on different systems, the source non-CDB or PDB cannot be closed, because AutoUpgrade has no access to it.
Options
[yes | no]
The default value is yes
.
Examples
sales3.close_source=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
Common Parameters for the AutoUpgrade Configuration File (Upgrade and Patch)
You can use common parameters for the AutoUpgrade configuration file
(config) with both upgrade
and software maintenance -patch
operations.
Parent topic: AutoUpgrade Command-Line Parameters and Options
create_listener
(Optional) Creates a listener in the new Oracle home after an upgrade.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.During Deploy mode, AutoUpgrade can create a listener in the new (target) Oracle home. There are four options:
- (Default) Create a new listener named
LISTENER
on port 1521. - Specify both a custom listener name and port number. (For example: my_listener:49152)
- Create multiple listeners by providing a comma-delimited list of listener names
and ports. (For example:
listener_name1:listener_port1,listener_name2:listener_port2, . . .
). - Provide the path to a response file to configure the listener
settings, such as a response file generated by NETCA. (For example:
/path/to/responsefile.rsp
)
Use this parameter if you want to create a listener in the new Oracle home, particularly if you want to create a listener based on specific requirements.
Note:
Listeners must have unique names. To avoid conflicts during migration from the earlier release Oracle home to the new release Oracle home, and you use this parameter option, then you have an existing listener in your current Oracle home, then you must create a unique listener name.Other AutoUpgrade modes can validate create_listener
configuration choices, but the actual creation of listeners only happens during
Deploy mode, during the Postupgrade stage. After the listener is created,
AutoUpgrade automatically starts the listener. If an error occurs, AutoUpgrade will
continue to complete the upgrade job without interruption, but log a warning message
that provides information about why the listener creation process failed. This
ensures a seamless upgrade experience while maintaining visibility into any issues
that can arise during the listener creation process.
When this parameter is set, AutoUpgrade uses a response file template to creates a
response file for the listener options that you specify in the target Oracle home.
By default, this response file is located at
Oracle_home/assistants/netca/netca.rsp
.
On Microsoft Windows platforms, the Oracle home is installed with secure
user privileges, so AutoUpgrade requires explicit authentication privileges to
create the listener. Accordingly, if you use this parameter, then you must modify
the default netca.rsp
file by updating the
SERVICEUSERPASSWORD
parameter as follows:
-
Remove the leading hash symbol (
#
). -
Replace the hash symbol with the actual password for the database installation owner user account enclosed with quotes. For example:
SERVICEUSERPASSWORD="*******"
Syntax
create_lister[=default|my_listener:my_port|
listener_name1:listener_port1,listener_name2:listener_port2, . .
.
|/path/to/responsefile.rsp]
Restrictions
- You must specify listeners using alphanumeric characters for the name and numeric values for the port.
- If you use a path to a response file, then the response file target must be a valid response file.
Examples
Create a listener with default values:
upg1.create_listener=default
Create a listener with the name sales_listener
on port 54321:
upg1.create_listener=sales_listener:54321
Parent topic: AutoUpgrade Command-Line Parameters and Options
defer_standby_log_shipping
log_archive_dest_n
) are set to
deferred.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.By default, log shipping occurs as part of the upgrade. When Autoupgrade defers log shipping, you receive a notice that log shipping is deferred, and that after the upgrade completes successfully, you need to reenable shipping logs from the primary database to the secondary database.
Note:
This configuration file parameter affects not only standby databases, but all products or services that receive redo from the primary database, such as Oracle Zero Data Loss Recovery Appliance (ZDLRA) real-time log transport, and Oracle GoldenGate downstream capture.Options
[yes | no]
The default value is no
The default is no (log-shipping is not deferred). If you change the
default to Yes
, then log shipping is deferred, and you must choose
to re-enable it manually after upgrade.
Example
defer_standby_log_shipping=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
del_after_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of a
PFILE
whose parameters you want to have removed after upgrade.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Examples
sales3.del_after_upgrade_pfile=/path/to/my/pfile_del.ora
Parent topic: AutoUpgrade Command-Line Parameters and Options
del_after_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of a
PFILE
whose parameters you want to have removed after the
PFILE
upgrade.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This specification applies to all databases in the user configuration file.
Example
global.del_after_upgrade_pfile=/path/to/my/del_after.ora
Parent topic: AutoUpgrade Command-Line Parameters and Options
del_during_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of a PFILE whose parameters you want to have removed during upgrade.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Examples
sales3.del_during_upgrade_pfile=/path/to/my/oldpfile.ora
Parent topic: AutoUpgrade Command-Line Parameters and Options
del_during_upgrade_pfile
(Optional for AutoUpgrade upgrades) Specifies a path and file name of a
PFILE
whose parameters you want to have removed during the
PFILE
upgrade.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This specification applies to all databases in the user configuration file.
Example
global.del_during_upgrade_pfile=/path/to/my/del_during.ora
Parent topic: AutoUpgrade Command-Line Parameters and Options
delete_wincredential_file
(Optional) Deletes the Microsoft Windows credential object file when the AutoUpgrade job is complete.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.When set to NO
, AutoUpgrade does not delete the Microsoft Windows
file credential after the AutoUpgrade job first using the credential is completed.
The default value is YES
.
The purpose of this parameter is to enable you to choose whether
AutoUpgrade immediately deletes the Microsoft Windows object credentials loaded with
the wincredential
parameter after these credentials are first used,
or if you want to be able to reuse the Windows object credential with other
AutoUpgrade patching or upgrading operations.
Note:
If you setdelete_wincredential_file
to NO
, then
you must manually delete that credential after your AutoUpgrade jobs are complete.
AutoUpgrade provides a notice in the postupgrade summary report to tell you that the
Windows credential file was not removed, and that you should remove this credential
file manually.
Use case:
You are performing multiple upgrades or patching operation with
AutoUpgrade, and you want to specify credentials for the owner of database binaries
on a Microsoft Windows server for more than one upgrade or patching operation so
that they can all complete automatically. When you specify the
wincredential
parameter to load the credentials, and then also
specify delete_wincredential_file
to NO
,
AutoUpgrade can use that credential for multiple upgrades or patches of the same
Oracle Database, or for different Oracle Databases. To use this feature, you must
have already created the Windows PowerShell credential object, and then specify that
credential object in the configuration file using
wincredential
.
Example
In the following example, the local configuration file setting
wincredential
provides the location where the Microsoft Windows
credentials have been loaded, and delete_wincredential_file=NO
specifies that AutoUpgrade does not automatically delete the Windows object
credential file after the db12201
database operation is complete.
global.autoupg_log_dir=C:\Users\oracle\autoupg
global.target.version=19.0.0
global.target_home=C:\u01\app\oracle\product\19\dbhome_1
upg1.sid=db12201
upg1.source_home=C:\u01\app\oracle\product\12.2\dbhome_1
upg1.log_dir=C:\Users\Oracle\autoupg
upg1.upgrade_node=localhost
upg1.target_base=C:\u01\app\oracle
upg1.target_version=19.0.0.0
upg1.wincredential=C:\Users\oracle\cred
upg1.delete_wincredential_file=NO
Parent topic: AutoUpgrade Command-Line Parameters and Options
dictionary_stats_after
(Optional) Specifies that AutoUpgrade gathers data dictionary statistics on the target database after the upgrade is complete.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.Oracle recommends that you gather dictionary statistics both before and after upgrading the database, because Data Dictionary tables are modified and created during the upgrade. When you specify yes, AutoUpgrade gathers dictionary statistics after the upgrade is completed.
Options
[yes | no]
The default value is Yes
.
Example
global.dictionary_stats_after=yes
sales.dictionary_stats_after=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
dictionary_stats_before
(Optional) Specifies that AutoUpgrade gathers data dictionary statistics on the source database before starting the upgrade.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.Oracle recommends that you gather dictionary statistics both before and after upgrading the database, because Data Dictionary tables are modified and created during the upgrade. When you specify yes, AutoUpgrade gathers dictionary statistics before beginning the upgrade.
Options
[yes | no]
The default value is Yes
.
Example
global.dictionary_stats_before=yes
sales.dictionary_stats_before=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
download
(Optional for AutoUpgrade patching) Specifies whether to automatically download patches from My Oracle Support. .
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Specifies whether to automatically download patches from My Oracle Support. The default is YES.
When set to YES, you must either load My Oracle Support (MOS)
credentials or an OAUTH token into AutoUpgrade Patching at the command line using
the -load_password
command-line option.
The patches that are downloaded are placed into the directory folder
specified by the folder
parameter.
If proxy information is required to connect to My Oracle Support, then
set proxy values using the Linux operating system environment variables
https_proxy
, http_proxy
, and
no_proxy
.
The supported format of the proxy definition is as follows, where
user_info
is a user account,
site
is a URL, and
port
is a designated port for the proxy
listener:
[https|http|socks5|socks]://(user_info@)site:port
Adding user_info
to the proxy definition is
optional, and has a format of username:password for the
credentials of the proxy.
Options
[yes | no]
The default value is yes
.
Examples
Override the default (yes) so that you use patches that you have downloaded manually instead of having AutoUpgrade download the patches automatically:
upg1.download=no
Parent topic: AutoUpgrade Command-Line Parameters and Options
drop_db_link
(Optional for AutoUpgrade upgrades) Specifies that the database link set up for an unplug-plug relocate (hot clone) upgrade is dropped after successful job completion.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.After an unplug-plug relocate (hot clone) job using a database link
specified by the parameter source_dblink
, the
drop_db_link
parameter specifies to drop the link after the
successful completion of that job. This parameter applies only to jobs that are
using the source_dblink
parameter. Any error encountered during
drop of the database link does not result in overall job error, but is noted in the
AutoUpgrade log files only.
Note:
This option is available for source database releases Oracle Database 12.1.0.2 and later.Example
In the following example, after using a link set up withsource_dblink
, the drop_db_link specifies that the database link is
dropped after successful completion.
upg1.drop_db_link
Parent topic: AutoUpgrade Command-Line Parameters and Options
drop_grp_after_patching
(Optional for AutoUpgrade patching) Deletes the Guaranteed Restore Point (GRP) after database patch maintenance.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.If you select this parameter option, then GRP is deleted after the AutoUpgrade patch maintenance completes successfully.
Options
[yes | no]
The default value is no
.
Example
sales4.drop_grp_after_patching=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
drop_grp_after_upgrade
(Optional for AutoUpgrade upgrades) Deletes the Guaranteed Restore Point (GRP) after database upgrade.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.If you select this option, then GRP is deleted after upgrade completes
successfully. If you set raise_compatible
to yes
,
then you must also set the parameter drop_grp_after_upgrade
to
yes
.
Options
[yes | no]
The default value is no
.
Example
global.drop_grp_after_upgrade=yes
sales.drop_grp_after_upgrade=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
drop_win_src_service
(Optional for upgrades only) For upgrades on Microsoft Windows, specifies whether to drop the Windows operating system service for the source Oracle Database after upgrade.
Usage Notes
By default, for Oracle Database upgrades on Microsoft Windows operating
systems, after AutoUpgrade shuts down the Windows Oracle Database service and
completes the upgrade, it leaves the service in place. Leaving the service down but
in place gives you the option to restore the database to the source Oracle home
without having to recreate the Microsoft Windows service for the database. However,
you can choose to have the Microsoft Windows service for the source database removed
automatically after upgrade is completed successfully. If either
no
is specified, or no value is is specified, then the service
is shut down on the source, but left in place after the upgrade.
Options
[yes | no]
The default value is no
.
Examples
upg1.drop_win_src_service=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
em_blackout_suffix
(Optional) Enables you to specify a suffix to add to the default autoupgrade blackout
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.The Enterprise Manager command-line interface (EMCLI) enables AutoUpgrade to use scheduled blackouts to suspend any data collection activity on one or more monitored targets. Use this parameter to provide a specific suffix for AutoUpgrade blackouts. By default, when you enable the use of EMCLI to create blackouts, the default blackout name in the EMCLI log file is as follows, where sid is the system identifier of the database where the blackout is enabled:
blackout_AutoUpgrade_sid
If you specify em_blackout_suffix
, then in addition to
the system identifier (sid
), you can specify a
suffix, so that you can track AutoUpgrade processes more precisely
(blackout-suffix
).
Syntax
em_blackout_AutoUpgrade_sid_blackout-suffix
Example
Suppose you are updating a set of upgrades in your configuraiton file, and in the set
of upgrades specified with the prefix upg1
, you want to attach a
suffix to the database with the system identifier sales1
. The
suffix you choose is q3-updates
. To do this, you use
em_blackout_autoupgrade as follows:
upg1.em_blackout_autoupgrade_sid_q3-updates
Parent topic: AutoUpgrade Command-Line Parameters and Options
em_target_name
(Optional) Enables you to specify that the database that you name is monitored by Enterprise Manager so the monitoring can be updated to the new Oracle home.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.AutoUpgade can use the Enterprise Manager command-line interface (EMCLI) to update Enterprise Manager monitoring to the new Oracle Database home. However, you must provide the Enterprise Manager target name so that AutoUpgade is configured to update the database to the new Oracle home.
Syntax
Enter the parameter in your configuration file, where
em-target-name
is the Enterprise Manager target name where you
need to update the Oracle home attribute:
em_target_name=em-target-name
You must enter the complete Enterprise Manager target name.
Example
Update the Enterprise Manager monitored database
sales1_host1.domain.internal
to point to the new Oracle
Home
upg1.em_target_name=sales1_host1.domain.internal
Parent topic: AutoUpgrade Command-Line Parameters and Options
emcli_path
(Optional) Enables you to specify the path to the Enterprise Manager Command Line Interface (EMCLI) command.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.AutoUpgade can use the Enterprise Manager command-line interface (EMCLI) to perform tasks during upgrade or patching. However, to access the command, you must provide AutoUpgrade the path to the EMCTL path for the database that EMCTL is monitoring to update the monitored database to the new Oracle home.
Syntax
emctl_path=path-to-emctl-location
Example
Suppose you are updating a set of upgrades in your configuration file,
and in the set of upgrades specified with the prefix upg1
, you want
to update Enterprise Manager monitored databases to their new Oracle home. The path
to the Enterprise Manager command-line interface home is
var/opt/dbascripts/emcli/
. To do this, you use
emctl_path
as follows:
upg1.emctl_path=var/opt/dbascripts/emcli/
Parent topic: AutoUpgrade Command-Line Parameters and Options
enable_local_undo
(Optional for AutoUpgrade upgrades) For a CDB upgrade, specifies whether or
not LOCAL
undo should be enabled before the upgrade of
CDB$ROOT
.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.If you select this option, then AutoUpgrade runs the following statement
before upgrade: ALTER DATABASE LOCAL UNDO ON;
.
When local undo is first enabled, the size of the undo tablespace in
PDB$SEED
is determined as a factor of the size of the undo
tablespace in CDB$ROOT
. The default is 30 percent of the undo
tablespace size. Every other PDB in the CDB inherits this property from
PDB$SEED
. Ensure that there is enough space to allocate new
UNDO
tablespaces.
Options
[yes | no]
The default value is no
.
Example
enable_local_undo=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
env
(Optional) Specifies custom operating system environment variables set on
your operating system, excluding ORACLE_SID
, ORACLE_HOME
,
ORACLE_BASE
, and TNS_ADMIN
.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.Use this parameter to provide environment setting that are indicated in
the database sqlnet.ora
file, such as secure socket layer cipher
suites that are used for Oracle Wallet. Multiple settings are comma-delimited.
Syntax:
prefix=VARIABLE1=value1 [, VARIABLE2=value2, ...]
Example
Assume that for the PDB sales2
, the value for
WALLET_LOCATION
is set using custom environment variables:
WALLET_LOCATION=
(SOURCE=
(METHOD=file)
(METHOD_DATA=(DIRECTORY=/databases/wallets/$CUSTOM_ENV1/$CUSTOM_ENV2))
In that case, for AutoUpgrade to know what those custom environment
variables are, you must provide them using the env
parameter, where
dir1
is the path indicated
by the environment variable CUSTOM_ENV1
, and dir2
is the path specified by
CUSTOM_ENV2
:
sales2.env=CUSTOM_ENV1=dir1,CUSTOM_ENV2=dir2
Parent topic: AutoUpgrade Command-Line Parameters and Options
exclusion_list
(Optional for AutoUpgrade upgrades) Sets a list of PDBs that you want to be excluded from the AutoUpgrade run. This parameter only applies to the multitenant architecture (CDB) databases. If you are plugging in and upgrading a non-CDB database, then this parameter is ignored.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Use this parameter to provide a list of PDBs to exclude from the AutoUpgrade run. The PDB list is comma-delimited. It can contain either a list of PDB names, or an asterisk character (*), which indicates that you want ot exclude all PDBs that are open on the CDB at the time that you run AutoUpgrade.
Syntax:
prefix.exclusion_list=[pdb-name|*][,pdb-name,...]
Examples
Assume that you want to exclude PDBs pdb1
and
pdb2
from the upgrade of cdb sales1. The following entry in the
configuration file excludes pdb1
and pdb2
from
being processed during the AutoUpgrade run:
sales1.exclusion_list=pdb1,pdb2
This entry in the configuration file excludes all open PDBs from the CDB
sales2
:
sales2.exclusion_list=*
Parent topic: AutoUpgrade Command-Line Parameters and Options
export_rman_backup_for_noncdb_to_pdb
(Optional for AutoUpgrade upgrades) Specifies that AutoUpgrade transports metadata from the source non-CDB database to the target PDB database as part of the conversion process.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.When converting a non-CDB to a PDB, you can extract the RMAN metadata from the source database, and put it into the target database, so that the metadata it will be available after the PDB conversion. Using this parameter enables the backups to be used as "pre-plugin" backups. If you want to restore the PDB right after plug-in, then the pre-plugin backups option can help to save time and effort.
This parameter applies to non-CDB to PDB conversions only (not with refreshable clone PDBs). In all other cases, the parameter should be ignored.
Options
[yes | no]
The default value is no
.
Example
sales.export_rman_backup_for_noncdb_to_pdb=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
fixed_stats_before
(Optional) Specifies that AutoUpgrade gathers fixed object statistics on the source database before starting the upgrade.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.Before an upgrade, Oracle recommends that you regather fixed object statistics.
Fixed objects are the X$
tables and their indexes.
V$
performance views are defined through X$
tables. Gathering fixed object statistics is valuable for database performance,
because these statistics help the optimizer generate good execution plans, which can
improve database performance. Failing to obtain representative statistics can lead
to suboptimal execution plans, which can cause significant performance problems.
Options
[yes | no]
The default value is Yes
.
Example
global.fixed_stats_before=yes
sales.fixed_stats_before=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
folder
(Required for AutoUpgrade patching) Specifies the directory that contains the patch zip files as well as any Oracle Database base images that are required.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.For AutoUpgrade to perform patching, you must identify the directory that contains the patch zip files. This directory must also contain the Oracle Database base image. There is no default value. You must provide the directory path. This parameter also is used in conjunction with the download parameter as follows:
When download=YES
, the directory specified by the
folder
parameter is the directory to which the patches will be
downloaded
When download=NO
, the directory specified by the
folder
parameter is the directory that must contain the patches
that have been manually downloaded.
The directory that you specify with the folder
parameter must contain the base image of the source database's release (for example,
Oracle Database Release 19.3).
Examples
upg1.folder=/storage/patches
Parent topic: AutoUpgrade Command-Line Parameters and Options
Global Common Parameters for the AutoUpgrade Config File
The Common global parameters for the AutoUpgrade configuration file (config)
enable you to set a global parameter for both software maintenance
(-patch
) and upgrade
(upgrade
).
Parent topic: AutoUpgrade Command-Line Parameters and Options
Global Patch Parameters for the AutoUpgrade Config File
The patch global parameters for the AutoUpgrade configuration file (config)
enable you to set a global parameter for software maintenance
(-patch
).
Parent topic: AutoUpgrade Command-Line Parameters and Options
Global Upgrade Parameters for the AutoUpgrade Config File
The upgrade global parameters for the AutoUpgrade configuration file
(config) enable you to set a global parameter for upgrades
(upgrade
).
Parent topic: AutoUpgrade Command-Line Parameters and Options
global_log_dir
(Optional) Sets the location of the AutoUpgrade log files, and temporary files that belong to global modules, which AutoUpgrade uses.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.This configuration parameter is used for patching and
upgrade. This parameter replaces autoupg_log_dir
parameter, which is deprecated. You can configure a different log
directory path in the userconfig
file in the logs
directory for a specific prefix.
If you do not set this parameter to a path, then by default
the log files are placed in the location indicated by the
orabase
utility for the databases that you
include in your configuration file. In that case, the default logs
directory is in the path ORACLE_BASE/cfgtoollogs/autoupgrade_patching
.
If the orabase
utility fails for all
databases included in the configuration file, then the log file
location is then based on the temp
directory for
the user running AutoUpgrade.
Examples
global.global_log_dir=/path/to/my/global/log/dir
Configure different log directory path in the
userconfig
file in the logs directory for a
specific prefix
global.global_log_dir=/path/to/my/global/log/dir
myprefix.log_dir=global.global_log_dir:different/path
The result of using this syntax is that log files and
temporary files are placed in the following path for databases
identified by the prefix myprefix
:
/path/to/my/global/log/dir/different/path
The following is an example of a configuration file suing the global_log_dir parameter:
global.global_log_dir=/logs/patching
global.keystore=/secure/keystore
upg1.sid=DB19X
upg1.source_home=/databases/19x/dbhome_1
upg1.target_home=/databases/19x/dbhome_2
upg1.folder=/storage/patches
upg1.download=YES
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.account_type
(Optional) for AutoUpgrade patching) On Microsoft Windows, this option specifies the type of account to use when creating the target ORACLE_HOME.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.On Microsoft Windows, the Oracle Home User can be either a Windows Virtual Account (VIRTUAL
), a Windows Built-in Account (BUILT_IN
), or a
standard Windows User Account (not an Administrator
account) (USER
).
If a Windows Virtual Account is used, then it enables you to install an Oracle Database and create and manage Database services without passwords. If a Built-in Account is used, then no user name or password is required during installation and administration. If a Windows User Account is used as Oracle Home User, then you must provide the user name and password during installation and some of the administration tasks. A Virtual Account can be used as the Oracle Home User for Oracle Database Single Instance installations. Virtual accounts do not require a user name or password during installation and administration.
Note:
To use this option, the Windows user account (nonadministrative user) must exist before you run AutoUpgrade. AutoUpgrade cannot create these users.Options
[VIRTUAL|BUILT_IN|USER]
Examples
In this example, you specify the Oracle Home User account to be a Built-in account:
upg1.home_settings.account_type=built_in
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.asm
(Optiona for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for Oracle ASM
(asm
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Note:
This option is not available on Microsoft Windows platforms.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has the Oracle Automatic Storage
Management (asm
) binary turned off. This parameter instructs
AutoUpgrade to turn the asm
binary to ON in the target Oracle home.
upg1.home_settings.binopt.asm=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.dm
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for Oracle Data Mining
(dm
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration file
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Note:
This option is not available on Microsoft Windows platforms.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has the Oracle Data Mining
(dm
) binary turned off. This parameter instructs AutoUpgrade to
turn the dm
binary to ON in the target Oracle home.
upg1.home_settings.binopt.dm=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.jox
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME being created by AutoUpgrade Patching has the binary option for the JavaVM JIT Compiler (jox) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Note:
This option is not available on Microsoft Windows platforms.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has the JavaVM JIT Compiler
(jox
) binary turned off. This parameter instructs AutoUpgrade
to turn the DM binary to ON in the target Oracle home.
upg1.home_settings.binopt.jox=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.olap
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for the On Line Application
Processing (OLAP) options (olap
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has the On Line Application
Processing options (olap
) binary turned off. This parameter
instructs AutoUpgrade to turn the olap
binary to ON in the target
Oracle home.
upg1.home_settings.binopt.olap=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.part
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for Oracle Partitioning
(part
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has Oracle Partitioning
(part
) binary turned off. This parameter instructs AutoUpgrade
to turn the part
binary to ON in the target Oracle home.
upg1.home_settings.binopt.part=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.rac
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for Oracle RAC
(rac
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Note:
This option is not available on Microsoft Windows platforms.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has the Oracle Real Application
Clusters (Oracle RAC) binary (rac
) turned off. This parameter
instructs AutoUpgrade to turn the rac
binary to ON in the target
Oracle home.
upg1.home_settings.binopt.rac=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.rat
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for Oracle Real Application
Testing (rat
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has the Oracle Real Application
Testing binary (rat
) turned off. This parameter instructs
AutoUpgrade to turn the rat
binary to ON in the target Oracle home.
upg1.home_settings.binopt.rat=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.sdo
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for Oracle Spatial Data Option
Messages (sdo
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Note:
This option is not available on Microsoft Windows platforms.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has the Oracle Spatial Data
Option Messages (SDO) binary (sdo
) turned off. This parameter
instructs AutoUpgrade to turn the sdo
binary to ON in the target
Oracle home.
upg1.home_settings.binopt.sdo=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.binopt.uniaud
(Optional for AutoUpgrade patching) Specifies whether the target ORACLE_HOME
being created by AutoUpgrade Patching has the binary option for Oracle's unified auditing
feature (uniaud
) turned ON or OFF.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Oracle products and components are enabled or disabled at the binary
level in the source Oracle home. When a source Oracle home is defined in the
configuration file by using the local configuration parameter
source_home
, the value used for the target Oracle home matches
the status of the binary option for the source Oracle home; the default is to leave
the binary value unchanged. However you can choose to override the target Oracle
home setting by choosing either yes
or no
.
Options
[yes | no]
There is no default.
Examples
In this example, the source Oracle home has Oracle's unified auditing
feature binary (uniaud
) turned off. This parameter instructs
AutoUpgrade to turn the uniaud
binary to ON in the target Oracle
home.
upg1.home_settings.binopt.uniaud=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.cluster_nodes
(Optional for AutoUpgrade patching) Specifies the list of nodes in an Oracle Real Applications (Oracle RAC) cluster on which you want to run AutoUpgrade patching.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.The value of this parameter should be a comma-delimited list of node names, where each node name is the hostname of a node in the cluster. This option is only available on certified POSIX-compliant platforms.
Note:
Autoupgrade Patching on an Oracle RAC Database automatically applies the Oracle Clusterware patch that matches the RU version for the Oracle Clusterware software, even if the Oracle Clusterware value (OCW) is not defined in the patch parameter.Syntax
home_settings.cluster_nodes=node1[,node2,node3...]
In the syntax, node1, node2 and node3 are names of cluster member nodes in the Oracle RAC cluster.
Note:
Regardless of the specific nodes listed in the comma-delimited list, this parameter always runs on the local node where AutoUpgrade is run. For example, suppose you run AutoUpgrade patching from cluster membernode1
in
an Oracle RAC cluster with cluster members node1
and
node2
:
home_settings.cluster_nodes=node2
Because you are
running AutoUpgrade patching from node1
, AutoUpgrade patching
will run on both node1
(the local node) and
node2
.
Examples
In this example, when Autoupgrade Patching is run in deploy mode, the
configuration file instructs AutoUpgrade to create a new Oracle home in the target
home location on both node1 and node2, and move the source Oracle home on each node
(/databases/ee/product/19x/dbhome_1
) to the target Oracle home
(/home/oracle/newOH
) on each node.
global.global_log_dir=/home/oracle/autopatch
upg1.patch=RU,OPATCH
upg1.sid=raccdb191
upg1.source_home=/databases/ee/product/19x/dbhome_1
upg1.target_home=/home/oracle/newOH
upg1.folder=/home/oracle/patches
upg1.home_settings.cluster_nodes=node1,node2
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.edition
(Optional for AutoUpgrade patching) Specifies the Oracle Database edition that you want to use for creating the target ORACLE_HOME.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.When a source ORACLE_HOME is defined in the configuration file, the default value for edition matches the edition used for that ORACLE_HOME. Otherwise, there is no default value.
Options
Standard (SE2) or Enterprise Edition (EE):
[se2|ee]
Examples
In this example, you specify the Oracle Database edition to be Oracle Database Standard Edition.
upg1.home_settings.edition=se2
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.home_name
(Optional for AutoUpgrade patching) Specifies the Oracle home name that will
be used for the database in the inventory.xml
file in the Oracle Inventory
(oraInventory) directory when creating the target ORACLE_HOME.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.In a read/write ORACLE_HOME, the ORACLE_BASE_HOME path is the same as
the ORACLE_HOME directory. However, in a read-only ORACLE_HOME, the ORACLE_BASE_HOME
directory is not co-located with ORACLE_HOME, but instead is located at
ORACLE_BASE/homes/HOME_NAME. The value for HOME_NAME is the internal name for the
ORACLE_HOME. These home names are tracked in the oraInventory
directory, which contains a file called inventory.xml
that lists
the names of all the Oracle homes installed on the system. Oracle software owners
are members of this group. The default value is to use a generic name for the
database homes, but you can specify a particular name by using this option.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the Oracle home name change the database
home from a generic name, such as dbhome_2
, to be
inv_west
:
upg1.home_settings.home_name=inv_west
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.ignore_opatch_conflict
(Optional for AutoUpgrade patching) Specifies the conflict resolution strategy for resolving conflicts between patches caused by one-off patches.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This optional parameter enables you to configure a patching conflict
policy that AutoUpgrade can apply when AutoUpgrade patching performs OPatch
prerequisite checks. When you set a conflict policy using this parameter and
AutoUpgrade detects conflicts among the patches specified by the
patch
parameter, AutoUpgrade applies the patch conflict policy
to resolve the conflict.
If the conflict is only between the one-off patches
specified by the patch
parameter, then, based on the
home_settings.ignore_opatch_conflict
parameter value,
AutoUpgrade patching can automatically resolve conflicts between those patches and
proceed to complete the patching, without stopping with a patch conflict error.
Note:
If patch conflicts are between any other types of patches other than the one-off patches that you specify with thepatch
parameter, then AutoUpgrade will always stop and issue an
error, regardless of the ignore_patch_conflict
policy that you set.
Options
[error|keep_first|skip_all]
The default is error
. The values for
home_settings.ignore_opatch_conflict
are as follows:
-
error
(default) : When AutoUpgrade encounters patch conflicts, patching then stops. AutoUpgrade displays an error, indicating that there are conflicts among the specified patches. keep_first
: When AutoUpgrade encounters patch conflicts, it prioritizes installing the one-off patches based on the order in which they are entered in the configuration fileprefix.patch=RU,OPATCH,patch-number1,patch-number2,patch-number3...
parameter entry. When a conflict is found, the one-off patches that come first in the patch parameter value sequence continue to be installed, even if these patches conflict with patches that are specified later in the parameter patch priority list. At the end of the patching operation, AutoUpgrade reports the patches that could not be applied.-
skip_all
: AutoUpgrade patching automatically skips installing all conflicted one-offs patches and proceeds to install patches that do not have conflicts.
Examples
ignore_opatch_conflict=error
In this example, the ignore_opatch_conflict
option
either is not specified (in which case the default is set to
ERROR
), or this option is set in the configuration file to
ERROR
. As a result, if AutoUpgrade encounters any conflicts
between any of the one-off patches (101,102,103), then AutoUpgrade stops and
displays an error.
upg1.patch=RECOMMENDED,101,102,103
upg1.home_settings.ignore_opatch_conflict = ERROR
ignore_opatch_conflict=keep_first
In this example, the ignore_opatch_conflict
option is
set in the configuration file to KEEP_FIRST
.
upg1.patch=RU,OPATCH,OJVM,101,102,103,104,105,106,107,108
upg1.home_settings.ignore_opatch_conflict = KEEP_FIRST
Suppose conflict arise among the following one-off patches:
- 101,102
- 101,103
- 102,103
- 103,104
- 104,105
- 105,108
In this case, AutoUpgrade patching does not stop with an error message, but continues to install patches :(RU,OPATCH,OJVM,101,104,106,107,108), based on the order of their appearance in the patch parameter value sequence. AutoUpgrade automatically ignores installing patches 102,103, and 105. At the end of the patching operation, AutoUpgrade reports the patches that had conflicts (102,103,105), and were ignored, with the following message: "Conflicts are detected and ignored among the provided one-off patches for the following jobs."
ignore_opatch_conflict=skip_all
In this example, the ignore_opatch_conflict
option is set in the
configuration file to SKIP_ALL
.
upg1.patch=RU,OPATCH,OJVM,101,102,103,104,105
upg1.home_settings.ignore_opatch_conflict = SKIP_ALL
Suppose that there are conflicts, but they only exist between patches 103 and 104. In that event, AutoUpgrade ignores patch numbers 103 and 104, and completes installing patches RU,OPATCH,OJVM, 101, 102, and 105, without stopping to display an error. At the end of the process, AutoUpgrade reports that patches 103 and 104 had conflicts that were detected, so these patches were ignored.
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.ignore_prereq_failure
(Optional for AutoUpgrade patching) Specifies whether AutoUpgrade patching ignores any prerequisite check errors that occur during installation on an Oracle Real Application Clusters (Oracle RAC) target home.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Note:
Oracle highly recommends that you first address any prerequisite check conflict errors before you proceed.Options
[yes|no]
The default is no
.
Example
In the following example, the value is set to yes
.
AutoUpgrade patching will ignore any prerequisite check failure and continue new
target oracle home creation in node1
and node2
.
global.global_log_dir=/home/oracle/autopatch
upg1.patch=RU,OPATCH
upg1.sid=raccdb191
upg1.source_home=/databases/ee/product/19x/dbhome_1
upg1.target_home=/home/oracle/newOH
upg1.folder=/home/oracle/patches
upg1.home_settings.cluster_nodes=node1,node2
upg1.home_settings.ignore_prereq_failure=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.inventory_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the Oracle Inventory group (OINSTALL).
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Members of the Oracle Inventory group group are granted OINSTALL
privileges to read and write to the Oracle Inventory group directory
(oraInventory
). Oracle software owners are members of this
group. When oraInst.loc
already exists on the system, the default
value matches the specified operating system group that is already defined on the
system. Otherwise, the default value is oinstall
.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the OINSTALL group to be
oracle-owners
:
upg1.home_settings.inventory_group=oracle-owners
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.inventory_location
(Optional for AutoUpgrade patching) Specifies the directory that should be
used for the Oracle Database inventory (oraInventory
) directory.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.The Oracle Inventory directory (oraInventory
) maintains
an inventory of all installed Oracle software on the system. When
oraInst.loc
already exists on the system, the default value for
oraInventory
matches the specified
inventory_location
directory already defined. Otherwise, there
is no default value.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the Oracle Inventory to be in the path
location /u02/app/oraInventory
:
upg1.home_settings.inventory_location=/u02/app/oraInventory
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.oracle_base
(Optional for AutoUpgrade patching) Specifies the directory that should be used for the Oracle base directory.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.For both a read-only ORACLE_HOME and a read/write ORACLE_HOME, the
user-specific files, instance-specific files, and log files reside in a location
known as the ORACLE_BASE_HOME. An Oracle base home directory by default has an
Optimal Flexible Architecture (OFA) path, such as /u01/app/oracle/
.
If you prefer, you can change from the default Oracle base into some other path,
such as an /opt
path,
Examples
In this example, you specify the Oracle base home to be in the path
location /opt/oracle/databases/
:
upg1.home_settings.inventory_location=/opt/oracle/databases/
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.osbackupdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system OSBACKUPDBA backup and recovery system privileges group for an Oracle Database.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This option is used with AutoUpgrade patching when installing the target
ORACLE_HOME to specify the OSBACKUPDBA system privileges group. The user running
AutoUpgrade Patching must be a member of the specified group. By default, when a
source ORACLE_HOME is defined in the configuration file, the default value matches
the OSBACKUPDBA group used for that ORACLE_HOME. Otherwise, the default group uses
the group that is specified for home_settings.osdba_group
. You can
override those defaults by specifying a named OSBACKUPDBA group.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the OSBACKUPDBA group to be
oracle_backup
:
upg1.home_settings.osbackupdba_group=oracle_backup
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.dba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system DBA system privileges group (OSDBA) management for the database.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This option is used with AutoUpgrade patching when installing the target
ORACLE_HOME to specify the OSDBA system privileges group. Members of this group are
granted the SYSDBA system privileges to administer the database. The user running
AutoUpgrade Patching must be a member of the specified group. By default, when a
source ORACLE_HOME is defined in the configuration file, the default value matches
the OSDBA system privileges group used for that ORACLE_HOME. If the
source_home
is not defined, then the default for this parameter
then becomes dba
.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the OSDBA group to be
inv_dba
:
upg1.home_settings.osdba_group=inv_dba
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.osdgdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system OSDGDBA system privileges to administer and monitor Oracle Data Guard.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This option is used with AutoUpgrade patching when installing the target
ORACLE_HOME to specify the OSDGDBA system privileges group. The user running
AutoUpgrade Patching must be a member of the specified group. By default, when a
source ORACLE_HOME is defined in the configuration file, the default value matches
the OSDGDBA system privileges group used for that ORACLE_HOME. Otherwise, the
default group uses the group that is specified for
home_settings.osdba_group
. You can override those defaults by
specifying a named OSDGDBA group.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the OSDGDBA group to be
oracle_dg
:
upg1.home_settings.osdgdba_group=oracle_dg
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.oskmdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system SYSKM system privileges for encryption key management for applications such as Oracle Wallet Manager.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This option is used with AutoUpgrade patching when installing the target
ORACLE_HOME to specify the SYSKM system privileges group. The user running
AutoUpgrade Patching must be a member of the specified group. By default, when a
source ORACLE_HOME is defined in the configuration file, the default value matches
the SYSKM system privileges used for that ORACLE_HOME. Otherwise, the default group
uses the group that is specified for home_settings.osdba_group
. You
can override those defaults by specifying a named SYSKM group.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the SYSKM group to be
oracle_keystore
:
upg1.home_settings.osdgdba_group=oracle_keystore
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.oper_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system operator (OSOPER) system privileges group.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This option is used with AutoUpgrade patching when installing the target
ORACLE_HOME to specify the OSOPER system privileges group. Members of this group are
granted the OPERATOR system privileges to start up and shut down the database. The
user running AutoUpgrade Patching must be a member of the specified group. By
default, when a source ORACLE_HOME is defined in the configuration file, the default
value matches the OSOPER system privileges group used for that ORACLE_HOME.
Otherwise, the default group uses the group that is specified for
home_settings.osdba_group
. You can override those defaults by
specifying a named OSOPER group.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the OSOPER group to be
inv_oper
:
upg1.home_settings.osdba_group=inv_oper
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.osracdba_group
(Optional for AutoUpgrade patching) Specifies the group that is designated as the operating system SYSRAC privileges to perform day to day administration of Oracle Database on an Oracle RAC cluster.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This option is used with AutoUpgrade patching when installing the target
ORACLE_HOME to specify the operating system RACDBA system privileges group. The user
running AutoUpgrade Patching must be a member of the specified group. By default,
when a source ORACLE_HOME is defined in the configuration file, the default value
matches the RACDBA system privileges used for that ORACLE_HOME. Otherwise, the
default group uses the group that is specified for
home_settings.osdba_group
. You can override those defaults by
specifying a named RACDBA group.
Note:
This option is not available on Microsoft Windows platforms.
Examples
In this example, you specify the RACDBAgroup to be
oracle_rac
:
upg1.home_settings.osdgdba_group=oracle_rac
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.read_only
(Optional for AutoUpgrade patching) Specifies whether a Read-Only Oracle home should be enabled when creating the target ORACLE_HOME.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.A read-only Oracle home can simplify provisioning. In a read-only Oracle home, all the configuration data and log files reside outside of the read-only Oracle home. See your platform installation guide for more information about read-only Oracle homes.
When a source ORACLE_HOME is defined in the configuration file, the default value
matches the setting used for that ORACLE_HOME. Otherwise, the default for a
read-only Oracle home is no
. To provision a read-only Oracle home
for the target Oracle home, you can use this option to select a read-only Oracle
home by specifying this option with yes
.
Options
[yes|no]
The default is no
.
Examples
In this example, you specify that the target Oracle home should be a read-only Oracle home:
upg1.home_settings.read_only=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
home_settings.ru_apply
(Optional for AutoUpgrade patching) Specifies whether a release update (RU)
is installed at the same time as the ORACLE_HOME
, or installed as a
separate step by OPatch.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.When the parameter is specified to YES
on a platform
other than Microsoft Windows, the RU being installed during a deploy operation is
installed when runInstaller
is run using the
-applyRU
command line option. When the parameter is specified
to NO
, the RU is then installed separately by running OPatch after
the ORACLE_HOME has already been installed.
Note:
This option is not available on Microsoft Windows platforms.
Options
[yes|no}
The default value is no
, unless the current operating
system is Oracle Linux 9 or higher.
Examples
In this example, the parameter is specified to no
, indicating that
you plan to run OPatch after the Oracle home is installed.
upg1.home_settings.ru_apply=no
Parent topic: AutoUpgrade Command-Line Parameters and Options
Ignore Fixups and Checks Using the AutoUpgrade Configuration File
To skip an entire check and fixup step for a database, you can direct
AutoUpgrade to read the fixup runfix
flag from the fixups checklist file,
and set the flag for that fixup from YES
to SKIP
.
To override the default list of fixups that AutoUpgrade performs automatically for
upgrades, you can load an existing checklist of fixup steps in to AutoUpgrade by
using the local configuration file parameter checklist
. In the
checklist that you specify with the local parameter, you can set a precheck fixup as
follows:
YES
(the default): Run checks, and run fixupsNO
: Run checks, but do not run fixups.SKIP
: Do not run checks, and do not run fixups.
In the configuration file, the local parameter checklist is used to direct AutoUpgrade to an existing checklist file.
global.autoupg_log_dir=/home/oracle/autoupg
upg1.sid=db12204
upg1.source_home=/databases/ee/product/12.2.0/dbhome_1
upg1.target_home=/databases/ee/product/21.1.0/dbhome_1
upg1.checklist=/home/oracle/autoupg/db12204/100/prechecks/db11204_checklist.cfg
In the Fixups checklist file, the runfix
flag for the
DICTIONARY_STATS
fixup is is set to skip that step.
[SID] [db21.1.0]
==========================================
[container] [db21.1.0]
==========================================
[checkname] EXISTENCE_OF_DATAPUMP_AQ_TABLES
[stage] PRECHECKS
[fixup_available] YES
[runfix] YES
[severity] WARNING
----------------------------------------------------
[checkname] DICTIONARY_STATS
[stage] PRECHECKS
[fixup_available] YES
[runfix] _SKIP
[severity] RECOMMEND
----------------------------------------------------
Parent topic: AutoUpgrade Command-Line Parameters and Options
ignore_errors
(Optional for AutoUpgrade upgrades) Enables you to specify a comma-delimited list of specific Oracle errors that you want AutoUpgrade to ignore during the upgrade or patching process.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.If you add this parameter to your configuration file, then the error numbers that you specify are ignored during the upgrade for the upgrade prefix that you specify.
Examples
sales3.ignore_errors=ORA-48181,ORA-00001
Parent topic: AutoUpgrade Command-Line Parameters and Options
json_progress_writing_interval
(Optional) Sets the time interval for how often to write the AutoUpgrade progress JSON report.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.This parameter specifies how often the AutoUpgrade progress JSON report is written. If you do not set this parameter, then by default the AutoUpgrade progress JSON report interval is 30 seconds
Example
In the following example,global.json_progress_writing_interval=90
is used to
specify that the JSON progress report is written every 90 seconds to the log
directory specified by global.autoupg_log_dir
:
global.json_progress_writing_interval=90
global.autoupg_log_dir=/path/to/my/global/log/dir
Parent topic: AutoUpgrade Command-Line Parameters and Options
keep_pdb_save_state
(Optional for AutoUpgrade upgrades) Specifies that if the PDB has a saved state in the source CDB, then you can either save or not save the PDB state on the target CDB.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This parameter applies to the Unplug-Plug flow (including restorations).
If the PDB state is saved in the source CDB, then by default that same saved state
continues to be saved after the upgrade process (default is yes
).
When keep_pdb_save_state
is set to no
, the source
PDB state is not saved after the upgrade. You can choose to set
keep_pdb_save_state
to no
when you are advised
to do so in AutoUpgrade preupgrade checks. For example, with Oracle Real Application
Clusters (Oracle RAC) upgrades, Oracle recommends that you do not keep the source
PDB saved state.
Options
[yes | no]
The default value is yes
.
Example
sales1.keep_pdb_save_state.pdbA=no
Parent topic: AutoUpgrade Command-Line Parameters and Options
keep_source_pdb
(Optional for AutoUpgrade upgrades) Specifies if the source PDB in an unplug-plug upgrade operation is kept in a closed state instead of being removed from the source CDB.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.By default, the source PDB is removed from the source CDB during the
upgrade process. When keep_source_pdb
is set to
YES
, the source PDB is not removed from the earlier release
system. You are only able to set the parameter to YES
when the copy
option is specified in the parameter target_pdb_copy_option
. When
the copy option is not used, this parameter is ignored, because the PDB must be
dropped. Without a copy, the existing datafiles can only be used by a single
CDB.
Options
[yes | no]
The default value is no
.
Example
sales1.keep_source_pdb=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
keystore
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.You can use the keystore parameter to specify where you want AutoUpgrade to create a dedicated software keystore that is used exclusively by AutoUpgrade.
The AutoUpgrade keystore contains the file ewallet.p12
(similar to other kind of keystores used by the database). The file
is created when you use the save
command in the TDE
prompt. If you choose to generate an auto-login keystore, then the
file cwallet.sso
is created as well. If you have an
auto-login keystore, then AutoUpgrade does not prompt for a keystore
password when AutoUpgrade starts.
The keystore generated by AutoUpgrade contains sensitive information, and is protected by a password that you choose when the keystore is used for the first time. Each time changes are made to the keystore, the password must be supplied. Unless you decide to create an auto-login keystore for AutoUpgrade, each time you start AutoUpgrade, and AutoUpgrade requires information from the keystore, you must provide the keystore password.
Caution:
Because the directory you specify withglobal.keystore
contains a software keystore, it should be protected using the same
security best practices as you use with all other highly secure
keystore files.
Example
In the following example, replaceORACLE_SID
with the system
identifier of the database using the keystore.
global.keystore=/etc/oracle/keystores/ORACLE_SID/autoupgrade
Parent topic: AutoUpgrade Command-Line Parameters and Options
Local Common Parameters for the AutoUpgrade Config File
The common Local parameters enable you to configure AutoUpgrade processing
in the configuration file (config) for specific Oracle Databases
either for software maintenance (-patch
) or upgrade
(upgrade
).
Parent topic: AutoUpgrade Command-Line Parameters and Options
Local Configuration File Parameter Fixups Checklist Example
To include or exclude specific fixups for individual databases during upgrades, use the local configuration file checklist.
In this example, there is a local checklist file called
sales4_checklist.cfg
, which provides a preupgrade
fixup checklist for the database sales4
. A portion of the
file contains the following settings:
[checkname] DICTIONARY_STATS
[stage] PRECHECKS
[fixup_available] YES
[runfix] YES
[severity] RECOMMEND
You can change the default fixup for DICTIONARY_STATS
to exclude
performing a fixup for the database sales4
by changing the
runfix
option for the check from
YES
to NO
:
[checkname] DICTIONARY_STATS
[stage] PRECHECKS
[fixup_available] YES
[runfix] NO
[severity] RECOMMEND
You can also specify to bypass (or "skip") performing the
DICTIONARY_STATS
database check entirely:
[checkname] DICTIONARY_STATS
[stage] PRECHECKS
[fixup_available] YES
[runfix] SKIP
Parent topic: AutoUpgrade Command-Line Parameters and Options
Local Patch Parameters for the AutoUpgrade Config File
The patch parameters enable you to configure AutoUpgrade processing in the
configuration file (config) for specific Oracle Databases for
software maintenance (-patch
).
Parent topic: AutoUpgrade Command-Line Parameters and Options
Local Upgrade Parameters for the AutoUpgrade Config File
The upgrade local parameters enable you to configure AutoUpgrade processing
in the configuration file (config) for specific Oracle Databases for
upgrades (upgrade
).
Parent topic: AutoUpgrade Command-Line Parameters and Options
Locally Modifiable Global Common Parameters for the AutoUpgrade Configuration File
The Common locally modifiable global parameters for the AutoUpgrade configuration file enable you to set modifiable global parameters in the configuration (config) file that can be overwritten by a database-specific local parameter.
Parent topic: AutoUpgrade Command-Line Parameters and Options
revert_after_action.deploy
(Optional for AutoUpgrade patching) In deploy
mode,
specifies a custom action that you want to have run on the operating system after a system
restoration is completed for the specific database job addressed by the prefix.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.The script that you use must be in the form of name.ext
(for example, myscript.sh
), so that AutoUpgrade can identify the
type of script that you want to run. Permitted extension options:
- Unix shell (
.sh
) - Microsoft Windows batch (
.bat
,.cmd
) - Microsoft Windows PowerShell (
.ps1
) - Oracle SQL file (
.sql)
, with a local operation only designated by the prefix.
Note:
Therevert_after_action.deploy
parameter for AutoUpgrade patching
and the local parameter revert_action
parameter cannot be specified
in the same configuration file.
By default, if the script fails, then AutoUpgrade continues to run. Use
the Y
flag to specify that AutoUpgrade stops if the operating
system detects that your script fails. If the script finishes with a status
different than 0
, then it is considered a failed completion.
For patching operations, the local
revert_after_action.deploy
parameter can specify a SQL script,
which then runs on the database using the target Oracle Database binaries on a
non-CDB Oracle home, or on CDB$ROOT
. If you want to run additional
container-specific actions, then they must be set within the code. For more complex
scenarios, you can run container-specific actions in a shell.
The output of the script is captured and stored in files. Both
stdout
and stderr
are captured. The files are
stored in the preupgrade
subdirectory in the directory matching the
specific database or job.
The following environment variables are set in the shell that runs the script:
ORACLE_SID
ORACLE_UNQNAME
ORACLE_BASE
ORACLE_HOME
TNS_ADMIN
Examples
Run the specified script after AutoUpgrade completes processing
deploy
mode, with the Y
flag set to stop
AutoUpgrade if the script fails:
sales.revert_after_action.deploy=/user/path/script.sh Y
Run the specified script after AutoUpgrade completes processing
deploy
mode, with AutoUpgrade set to continue to run if the
script fails:
sales4.revert_after_action.deploy=/user/path/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
revert_before_action
(Optional) Specifies a custom action that you want to have run on the operating system before a system restoration is completed for the specific database job addressed by the prefix, and the database is up.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.The action that you specify with revert_before_action
runs on the target Oracle home binaries before database restoration is started, and
the database is up.
The script that you specify to run must be in the form of
name.ext
(for example, myscript.sh
), so that
AutoUpgrade can identify the type of script that you want to run. Permitted
extension options:
- Unix shell (
.sh
) - Microsoft Windows batch (
.bat
,.cmd
) - Microsoft Windows PowerShell (
.ps1
) - Oracle SQL script (
.sql
), with a local operation on the database designated by therevert_before_action
parameter prefix.
Options
Stop on fail: [Y|N
]. The default is N
.
By default, if the specified script fails, then AutoUpgrade continues to
run (N
. To specify that AutoUpgrade stops if the script fails, use
the Y
flag. If the script finishes running on the operating system
with a status different than 0
, then AutoUpgrade identifies the
script as failed.
Examples
Run the script you specify on the operating system before AutoUpgrade
starts the restoration, with the Y
flag set to stop AutoUpgrade if
the script fails:
sales3.revert_before_action =/user/path/script.sh Y
Run the script you specify on the operating system before AutoUpgrade
starts the restoration. With no flag, the default stop on fail option is
N
, so AutoUpgrade continues to run if the script fails:
sales3.revert_before_action =/user/path/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
revert_before_action.create_home
(Optional for AutoUpgrade patching) In create_home
mode,
specifies a custom action that you want to have run on the operating system after a system
restoration is completed for the specific database job addressed by the prefix.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.For patching operations, the local
revert_before_action.create_home
can start a script to revert
an action before creating an Oracle home for the patched database using the target
Oracle Database binaries on a non-CDB Oracle home, or on CDB$ROOT
.
You must specify the new Oracle home path.
The following environment variables are set in the shell that runs the script:
ORACLE_SID
ORACLE_UNQNAME
ORACLE_BASE
ORACLE_HOME
TNS_ADMIN
Syntax
prefix.revert_before_action.create_home=/my/new/oracle/home/
Examples
Run the specified script to revert an action before AutoUpgrade starts
processing create_home
mode, with the Y
flag set
to stop AutoUpgrade if the script fails:
sales.revert_before_action.create_home=/user/path/script.sh Y
Run the specified script to revert an action before AutoUpgrade starts
processing create_home
mode, with AutoUpgrade set to continue to
run if the script fails:
sales4.revert_before_action.create_home=/user/path/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
revert_before_action.deploy
(Optional for AutoUpgrade patching). In deploy
mode,
specifies a custom script to revert an action before starting the upgrade job for the
specific database job addressed by the prefix.
Usage Notes
Note:
For use with AutoUpgrade patching only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.The script that you use must be in the form of name.ext
(for example, myscript.sh
), so that AutoUpgrade can identify the
type of script that you want to run. Permitted extension options:
- Unix shell (
.sh
) - Microsoft Windows batch (
.bat
,.cmd
) - Microsoft Windows PowerShell (
.ps1
) - Oracle SQL file (
.sql)
, with a local operation only designated by the prefix.
Note:
Therevert_before_action.deploy
parameter for AutoUpgrade patching
and the local parameter before_action
parameter cannot be specified
in the same configuration file.
By default, if the script fails, then AutoUpgrade continues to run. Use
the Y
flag to specify that AutoUpgrade stops if the operating
system detects that your script fails. If the script finishes with a status
different than 0
, then it is considered a failed completion.
For patching operations, the local
revert_before_action.deploy
parameter can specify a SQL script,
which then runs on the database using the target Oracle Database binaries on a
non-CDB Oracle home, or on CDB$ROOT
. If you want to run additional
container-specific actions, then they must be set within the code. For more complex
scenarios, you can run container-specific actions in a shell.
The output of the script is captured and stored in files. Both
stdout
and stderr
are captured. The files are
stored in the preupgrade
subdirectory in the directory matching the
specific database or job.
The following environment variables are set in the shell that runs the script:
ORACLE_SID
ORACLE_UNQNAME
ORACLE_BASE
ORACLE_HOME
TNS_ADMIN
Examples
Run the specified script to revert an action before AutoUpgrade starts
processing deploy
mode, with the Y
flag set to
stop AutoUpgrade if the script fails:
sales.revert_before_action.deploy=/user/path/script.sh Y
Run the specified script to revert an action before AutoUpgrade starts
processing deploy
mode, with AutoUpgrade set to continue to run if
the script fails:
sales4.revert_before_action.deploy=/user/path/script.sh
Parent topic: AutoUpgrade Command-Line Parameters and Options
rman_catalog_connect_string
(Optional) Specifies the RMAN connection string used to connect to an RMAN database.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.To use this feature, you must save the RMAN username and password in the
keystore using the AutoUpgrade command-line parameter
load_password
.
Example
global.target_base=/u01/app/oracle
sales4.rman_catalog_connect_string=string-alias
run_dictionary_health
(Optional for AutoUpgrade upgrades) Specifies whether you run Oracle Dictionary Health Checks as part of preupgrade checks to identify database dictionary inconsistencies.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.To help to identify database dictionary inconsistencies, you can specify
that AutoUpgrade runs the DBMS_DICTIONARY_CHECK
PL/SQL package on
the source database as part of preupgrade checks. If set, the AutoUpgrade
run_dictionary_health
parameter enables you to specify for each
upgrade source database that AutoUpgrade runs either the full array of Oracle
Dictionary Health Checks on the database dictionary, or that it runs only the most
critical set of checks. If the check detects potential or critical problems with the
database dictionary, then it prevents the upgrade from starting.
Oracle Dictionary Health Check results are stored under the AutoUpgrade
precheck directory in the format dbname_healthcheck_result.log
, where dbname
is the name of the database on which
the check was run. For more information about Oracle Dictionary Health Check, refer
to the DBMS_HCHECK
package documentation in Oracle Database PL/SQL
Packages and Types Reference.
Options
[full| critical]
If the parameter is not set, then the default is to not run
DBMS_DICTIONARY_CHECK
.
Example
sales1.run_dictionary_health=full
sales2.run_dictionary_health=critical
Related Topics
Parent topic: AutoUpgrade Command-Line Parameters and Options
run_utlrp
(Optional) Enables or disables running a version of
utlrp.sql
as part of post upgrade, to recompile only invalid objects in
Oracle-maintained schemas.
Usage Notes
Note:
This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.The utlrp
utility recompiles all Data Dictionary
objects that become invalid during a database upgrade. If you set
run_utlrp=no
, or if you want invalid user objects also to be
recompiled, then Oracle recommends that you use this utility to recompile invalid
objects after upgrading with AutoUpgrade.
Note:
Starting with AutoUpgrade 23.1, when you run the AutoUpgrade utility,
AutoUpgrade runs the utlprpom.sql
script, and does not run
utlrp.sql
. When AutoUpgrade is used for upgrades to Oracle
Database 12c Release 2 (12.2.0.1) and later releases, AutoUpgrade only
recompiles invalid objects owned by Oracle-maintained schemas. Because database
upgrades do not need to touch user objects, AutoUpgrade maintains this policy
when it recompiles invalid objects.
Options
[yes | no]
The default value is yes
.
Example
prefix.run_utlrp=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
sid
(Required) Identifies the Oracle system identifier (SID) of the database that you want to upgrade.
Usage Notes
Note:
This parameter must be used both with AutoUpgrade upgrades and AutoUpgrade patching.This parameter is case-sensitive.
Example
sales1.sid=salesdb
Parent topic: AutoUpgrade Command-Line Parameters and Options
skip_tde_key_import
(Optional for AutoUpgrade upgrades) When set to yes
, the
upgrade is run, but import of the source database KeyStore into the target database is
skipped, without raising an error.
Deprecated
Note:
This parameter is deprecated, because it is no longer needed. It can
be removed in a future AutoUpgrade release. Instead of using this parameter,
Oracle recommends that you either use the -load_password
command line option to add the TDE password to AutoUpgrade's keystore, or add
the TDE password to a Secure External Password Store (SEPS).
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.You can use this option for nonCDB-to-PDB and unplug/plug operations. When import of the source database KeyStore into the target database is skipped, AutoUpgrade will leave the PDB open in upgrade mode, so that you can import the keys manually yourself. After you import the keys, you must then restart the database in normal mode.
Options
[yes | no]
The default value is no
.
Example
sales1.skip_tde_key_import=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
target_is_remote
(Optional for AutoUpgrade upgrades) Specifies whether the target CDB is located on the same system as the cloned PDB.
Usage Notes
Note:
For use with AutoUpgrade upgrades only. Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.This parameter applies to the Unplug-Plug flow when the target CDB is on a remote
host. To avoid the time spent on unnecessary checks, Oracle recommends that you set
target_is_remote
to yes
when the target CDB is
on a remote system.
By default, when you do not set this parameter, or it is set to no
,
AutoUpgrade performs checks with the assumption that the target CDB is on the same
system as the cloned PDB.
When target_is_remote
is set to yes
, AutoUpgrade
skips the TDE_PASSWORDS_REQUIRED
and
TARGET_CDB_AVAILABILITY
checks during the analyze phase. These
two checks are not applicable when the target CDB is on a remote system.
Options
[yes | no]
The default value is no
.
Example
In the following example, the target CDB upgrade identified with the prefixupg1
is on a remote host. To prevent running the the
TDE_PASSWORDS_REQUIRED
and TARGET_CDB_AVAILABILITY
checks, you set the parameter to yes
:
upg1.target_is_remote=yes
Parent topic: AutoUpgrade Command-Line Parameters and Options
load_password
load_password
enables you to enter passwords safely into
AutoUpgrade's keystore. When you run AutoUpgrade in analyze mode, you are
notified which passwords are needed, and can be loaded into the AutoUpgrade
keystore.
Property | Description |
---|---|
Parameter type | string |
Syntax |
|
Default value | None. AutoUpgrade prompts you for password input values in an interactive prompt. |
Description
To provide passwords required for upgrade, you can use the
load_password
parameter. This parameter must be used in
conjunction with the -config
parameter and the configuration file
global parameter keystore
, to designate the location of the
dedicated software keystore where AutoUpgrade securely stores passwords. The
-load_password
parameter takes no arguments. Instead, it starts
an interactive prompt with specific commands that enable you to provide information
required for the keystore. This option can be used to add Transparent Data
Encryption passwords (TDE), My Oracle Support credentials (MOS), Oracle Recovery
Manager (RMAN) credentials, and database SYS passwords (PWD). The command options
are slightly different for each of these use cases. Common options include the
following:
group [tde|pwd|rman|mos]
Specifies the scope of the
load_password
option:mos
: Specifies that theload_password
options in the group apply to the My Oracle Support user (MOS). This group option applies only when AutoUpgrade is used with the-patch
command line option.pwd
: Specifies that theload_password
options in the group apply to the specified database SYS password (PWD). This group option applies to both upgrades and patching.tde
: Specifies that theload_password
options in the group apply to Transparent Data Encryption (TDE). This option applies for both upgrades and patching.rman
: Specifies that theload_password
options in the group apply to the specified database RMAN password (RMAN). This group option applies only when AutoUpgrade is not used with the-patch
command line option.
-
help
Lists all the available
load_password
commands. -
exit
Exits the
load_password
interactive console. If the keystore has been modified and not yet saved, then you are prompted to determine if you want to save the keystore before exiting.
During the upgrade, AutoUpgrade places passwords in an encrypted password array in memory, so that AutoUpgrade can access source database keystores and resources. No passwords are written to SQL*Plus scripts during the upgrade. After AutoUpgrade no longer requires the passwords, these passwords are purged from memory. No log records are kept of the passwords.
Transparent Data Encryption (TDE) Group Options
Note:
- If you configure an Keystore External Password Store in the database, then AutoUpgrade detects the presence of an Keystore External Password Store, and uses this external password store instead of requiring manual input of the TDE keystore passwords. However, if all databases are configured with Keystore External Password Store, then in some situations, you can still need to define global.keystore.
- In some situations, AutoUpgrade needs access to the AutoUpgrade
keystore to write other sensitive information. For example, AutoUpgrade can
write transport secrets (passphrases) that are used by
ADMINISTER KEY MANAGEMENT EXPORT KEYS
andADMINISTRATER KEY MANAGEMENT IMPORT KEYS
commands to AutoUpgrade. - When you specify a keystore to load a Transparent Data Encryption passwords (TDE) group, the TDE keystore is for for the CDB root and any associated united mode PDBs. If the TDE keystore is not on the same local host CDB, then loading the TDE keystore fails for unplug-relocate operations.
For more information about Keystore External Password Stores, refer to Oracle Database Advanced Security Guide or Oracle Database Data Redaction Guide.
When you run AutoUpgrade using -mode analyze
,
AutoUpgrade detect which passwords are needed for the databases specified for
upgrade in your configuration file, and lists them in the preupgrade summary report.
Before the upgrade, you can then use -load_password
to enter the
passwords for the databases. These passwords are stored safely in AutoUpgrade's own
keystore, in the location specified by global.keystore
. The
passwords are used only to access the source database TDE keystores, and to write
the TDE passwords in the target keystores.
Caution:
Because the directory you specify AutoUpgrade to create withglobal.keystore
contains a software
keystore, it should be protected using the same security best practices as you use
with TDE keystore files.
-load_parameter
option at the command line, AutoUpgrade starts an
interactive console so that you can configure password options. The console indicates if
you need
-
add ORACLE_SID [-pdb isolated-pdb]
Adds a TDE password for the specified Oracle System identifier (
ORACLE_SID
).If you have an isolated PDB that requires a password, then use the optional
-pdb
parameter in the configuration file to specify an isolated PDB for which you want to provide a password. If the CDB root and all PDBs are configured in united mode, then the-pdb
parameter is not required, as the keystore is shared between the CDB root and all PDBs that are configured in united mode. -
delete ORACLE_SID [-pdb isolated-pdb]
Deletes a loaded password for the specified Oracle System identifier (
ORACLE_SID
).If you loaded a password for an isolated PDB that you want to delete, then use the optional
-pdb pdbname
parameter in the configuration file to specify the name of the isolated PDB whose password you want to delete. If the CDB root and all PDBs are configured in united mode, then the-pdb
parameter is not required. -
list
Lists each Oracle Database by Oracle System Identifier (
ORACLE_SID
), provides details for each database, and indicates if further actions are necessary to perform an encrypted database upgrade. AutoUpgrade starts a deploy mode only when there are no pending actions for any of the databases listed in the configuration file. If an action is required before a database can be upgraded, then the AutoUpgrade checktde_passwords_required
fails during the prechecks stage.
My Oracle Support (MOS) Credential Group Options
-
add -user email-address
The
add -user email-address
option stores My Oracle Support credentials in the AutoUpgrade Patching keystore, whereemail-address
is the user email that you specify. Whendownload=YES
, the credentials are used to connect to My Oracle Support so that AutoUpgrade can download the required patches. -
list
displays whether My Oracle Support credentials have been loaded into the keystore, and if so, whether the loaded credentials could be used successfully to connect to My Oracle Support. You can only load one set of credentials. -
delete -user
deletes the My Oracle Support credentials.
Oracle Recovery Manager (RMAN) Credential Group Options
-
add ORACLE_SID -user username
Adds the username and password for the specified Oracle System identifier (
ORACLE_SID
). -
delete ORACLE_SID -user username
Deletes username and password for the specified Oracle System identifier (
ORACLE_SID
). -
list
Lists each Oracle Database by Oracle System Identifier (
ORACLE_SID
), provides details for each database, and indicates if further actions are necessary. -
pwd
Specifies the RMAN password needed to connect to the specified database.
Database SYS Password (PWD) Credential Group Options
-
add ORACLE_SID -user username
Adds the username and password for the specified Oracle System identifier (
ORACLE_SID
). -
delete ORACLE_SID -user username
deletes username and password for the specified Oracle System identifier (
ORACLE_SID
). -
list
Lists each Oracle Database by Oracle System Identifier (
ORACLE_SID
), provides details for each database, and indicates if further actions are necessary to perform an encrypted database upgrade. AutoUpgrade starts a deploy mode only when there are no pending actions for any of the databases listed in the configuration file. If an action is required before a database can be upgraded, then the AutoUpgrade checktde_passwords_required
fails during the prechecks stage. -
pwd
Specifies the SYS password needed to connect to the specified database. Sampe options as RMAN
-
exit
Exits the
load_password
interactive console. If the keystore has been modified and not yet saved, then you are prompted to determine if you want to save the keystore before exiting.
Examples
TDE Keystore Passwords Added to AutoUpgrade Keystore
Run AutoUpgrade to add the TDE keystore passwords to AutoUpgrade's own
keystore, using a configuration file named myconfig.cfg
, where
-load_password
is used to prompt you for TDE passwords of any
database where the TDE keystore password is needed:
java -jar autoupgrade.jar -config myconfig.cfg -load_password
After the TDE passwords are loaded, you can then either run AutoUpgrade
in analyze
or config mode
:
java -jar autoupgrade.jar -config myfile.cfg -mode deploy
AutoUpgrade uses the TDE password files from its own keystore to access the source database TDE keystores, and to write the TDE passwords in the target database keystores.
Multiple Load Password Options Used with Multiple Source Database Upgrades
In the following example, all of the load_password
command options are used to load TDE passwords from source databases
db12201
, cdb122
, and db19x
to
the common target CDB
cdb19x
:
$ java -jar autoupgrade.jar -config config.cfg -load_password
Processing config file ...
Starting AutoUpgrade Password Loader - Type help for available options
Creating new keystore - Password required
Enter password:
Enter password again:
Keystore was successfully created
TDE> add cdb19x
Enter your secret/Password:
Re-enter your secret/Password:
TDE> add cdb122
Enter your secret/Password:
Re-enter your secret/Password:
TDE> add db12201
Enter your secret/Password:
Re-enter your secret/Password:
TDE> add db19x
Enter your secret/Password:
Re-enter your secret/Password:
TDE> delete cdb19x
TDE> list
+----------+----------------+------------------+-----------+------------------+
|ORACLE_SID|Action Required | TDE Password |SEPS Status|Active Wallet Type|
+----------+----------------+------------------+-----------+------------------+
| cdb122| | Verified| Inactive| Any|
| cdb19x|Add TDE password|No password loaded| Inactive| Any|
| db12201| | Verified| Inactive| Auto-login|
| db19x| | Verified| Inactive| Any|
+----------+----------------+------------------+-----------+------------------+
TDE> help
The following options are available
-----------------------------------
1 add
2 delete
3 list
4 group
5 save
6 help
7 exit
TDE> save
Convert the keystore to auto-login [YES|NO] ? YES
TDE> exit
AutoUpgrade Password Loader finished - Exiting AutoUpgrade
Adding an isolated PDB TDE Keystore Password Added to AutoUpgrade Keystore
In isolated mode, where a pluggable database (PDB) has its own keystore,
PDBs are allowed to independently create and manage their own keystore. For isolated
mode PDBs, start the AutoUpgrade Password Loader, and use the syntax add
Oracle_SID -pdb pdbname
, where Oracle_SID
is the name of the CDB root, and
pdbname
is the name of the
isolated PDB.
cdb19x
and the
isolated PDB name is iso
:
TDE> add cdb19x -pdb iso
Enter your secret/Password:
Re-enter your secret/Password:
load_win_credential
load_win_credential
uses
PowerShell to create a credential object so that AutoUpgrade can be run without
interruption during the upgrade.
Description
To provide passwords required for upgrade on Microsoft Windows
platforms, you can use the load_win_credential
parameter. This
parameter must be used in conjunction with the -config
parameter,
and with a configuration file that specifies the local
wincredential
parameter. The parameter starts up a Microsoft
Windows PowerShell credential request, where you can provide Administrator
credentials to create a PowerShell credential object. By default, the Windows
PowerShell Credential request is for the local machine. You provide the user name
for the credential (the owner of the Oracle binaries) and that user password.
Windows Powershell then generates a credential using the format database-name.xml,
where database-name is the name of the database that you specified in your local
configuration file SID entry. For example, upg1.sid=sales1
in the
configuration file with the wincredential
entry
upg1.wincredential=C:\Users\oracle\cred
generates the
powershell credential file sales1.xml
in the path
sales1.wincredential=C:\Users\oracle\cred
After AutoUpgrade no longer requires the passwords, these passwords are purged from memory. No log records are kept of the passwords.
Note:
If you do not provide a system identifier (SID) as an option to the
-load_win_credential
parameter, and if only one database is
specified in the configuration file (config file), then AutoUpgrade uses the
only SID in the configuration file. Specifying the SID is optional.
However, if two or more SIDs are specified in the config file, then you must specify the SID for each database, then AutoUpgrade is unable to identify for which SID it should use the credentials. The result is an error.
Usage Notes
When you run AutoUpgrade for the database upgrade, AutoUpgrade reads the
credential from the path specified by the local wincredential
, so
that AutoUpgrade is able to create services automatically in the Target database
without requiring an administrator to provide Administrator credentials manually
during the upgrade.
Be aware that the account used in your connection can be restricted by a local security policy so that it either is not allowed to log on, or the login may be denied. If that is the case, then you see an error such as the following:.
Start-Process : This command cannot be run due to the error:
Logon failure: the user has not been granted the requested
logon type at this computer.
At line:1 char:1
To work around that error, work with your Microsoft Windows administrator to add the user account running AutoUpgrade to the local policy setting:
- Log on to the system (preferably as an administrator user).
- Go to Local Security Policy.
- Navigate to Security Settings, select Local Policies, and select User Rights Assignment.
- For the following policies, verify that either the group to which the user
running AutoUpgrade belongs or the user account itself is added to the following
lists:
- Access this computer from Network
- Allow log on locally
- Allow log on through Remote Desktop Services
For details, see Microsoft Support: "Logon type has not been granted."
Example
In the following example, you complete these steps in order to automate calling the Administrator credentials during the upgrade:
-
Create the configuration file, using the
wincredential
local parameter to specify the location for the Windows Powershell credential for the source databasedb12201
:global.autoupg_log_dir=C:\Users\oracle\autoupg global.target.version=19.0.0 global.target_home=C:\u01\app\oracle\product\19\dbhome_1 upg1.sid=db12201 upg1.source_home=C:\u01\app\oracle\product\12.2\dbhome_1 upg1.log_dir=C:\Users\Oracle\autoupg upg1.upgrade_node=localhost upg1.target_base=C:\u01\app\oracle upg1.target_version=19.0.0.0 upg1.wincredential=C:\Users\oracle\cred
-
Run AutoUpgrade in Configuration mode, using the
load_win_credential
command-line parameter. If there s only one SID in your configuration file, then specifying the system identifier (SID
) is optional, but not required. For example:C:\Users\oracle>java -jar autoupgrade.jar -config config.cfg -load_win_credential db12201 AutoUpgrade 24.1.240306 launched with default internal options Processing config file ...
Note:
If the config file contains multiple SIDs, then you must specify the SID when you run AutoUpgrade. If you do not specify the SID when there are multiple SIDs in the configuration file, then the result is an error. - A Microsoft Windows Powershell Credential prompt opens. Provide the
credentials for the Oracle Database binary owner. PowerShell then generates the
credential object (in this example,
db12201.xml
), and places it in the path that you specified with thewincredential
parameter. -
During the upgrade, run AutoUpgrade using the configuration file that specifies the credential object path. For example:
C:\Users\oracle>java -jar autoupgrade.jar -config config.cfg -mode deploy
AutoUpgrade processes the upgrade without prompting you for credentials.
Suppose your configuration file contains two SIDs, db12201
and
db19x
:
upg1.sid=db12201
upg1.source_home=C:\databases\ee\product\12.2\dbhome_1
upg1.target_home=C:\databases\ee\product\18x\dbhome_1
upg1.wincredential=C:\Users\oracle\cred
upg2.sid=db19x
upg2.source_home=C:\databases\ee\product\18x\dbhome_1
upg2.target_home=C:\databases\ee\product\19x
upg2.wincredential=C:\Users\oracle\anothercred
In this case, running java -jar autoupgrade.jar -config config.cfg
-load_win_credential
without specifying the SID results in an error.
When you run AutoUpgrade in Configuration mode to load credentials, you must
provide the SID so that AutoUpgrade can load the credentials for that SID. For
example, to load the correct credentials for db12201
:
java -jar autoupgrade.jar -config config2.cfg -load_win_credential db12201
To load credentials for db19x
, you conversely must specify the
db19x
SID:
java -jar autoupgrade.jar -config config2.cfg -load_win_credential db19x
Related Topics
Parent topic: AutoUpgrade Command-Line Parameters and Options
mode
The AutoUpgrade parameter mode
value sets the mode from
which AutoUpgrade runs.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
|
Default value |
None. Choose one of the following options:
|
Examples
java -jar autoupgrade.jar -config config.cfg -mode analyze java -jar autoupgrade.jar -config config.cfg -mode deploy java -jar autoupgrade.jar -preupgrade "target_version=21" -mode fixups
Parent topic: AutoUpgrade Command-Line Parameters and Options
noconsole
The AutoUpgrade parameter noconsole
turns off the
AutoUpgrade console, so that AutoUpgrade runs using only configuration file information.
Property | Description |
---|---|
Parameter type |
string |
Syntax |
|
Description
When you use the noconsole
option, AutoUpgrade runs using only the
settings in the configuration file, without requiring console input.
Use the noconsole
option when you want to run
AutoUpgrade as part of a batch flow, or in scripts, such as in cases
where you want to analyze multiple databases. After the AutoUpgrade
jobs are finished, you can review the output of the Analyze mode
logs to see what is required to upgrade each of the databases
included with your configuration script.
Note:
You can run only one AutoUpgrade instance at a time that is associated with a given configuration file.
Usage Notes
In this example, AutoUpgrade is run in Analyze mode, using the configuration file in noconsole
mode.
java -jar autoupgrade.jar -config autoupgrade.cfg -mode analyze -noconsole
Parent topic: AutoUpgrade Command-Line Parameters and Options
Patch
The AutoUpgrade parameter patch
is used to specify that
AutoUpgrade is performing a patch operation, and not an upgrade operation.
Property | Description |
---|---|
Parameter type | String |
Syntax | -patch |
Default value | Not applicable |
Description
The patch
command-line parameter specifies that the autoupgrade.jar
command starts an AutoUpgrade patching operation.
Usage Notes
This parameter is used only with AutoUpgrade patching. It cannot be used with the
-preupgrade
command-line option. All other command-line options
can be used with the patch option.
The -mode
operations analyze, fixup, deploy, download,
and create_home are supported with the patch command-line parameter. The modes
download
and create_home
are specifically for
use with the patch parameter:
-mode download
: Specifies to download specified patches and then exit.-mode create_home
Specifies to create the new target Oracle home without requiring either a source database or source ORACLE_HOME.
Note:
Patching and upgrade operations are mutually incompatible. You can either perform a patching operation, or an upgrade operation, but not both in the same entry in the configuration file.Example
In this example, the patch parameter is used with -mode
download
to automatically download the patches specified in the
configuration file:
java -jar autoupgrade.jar -patch -mode download
Parent topic: AutoUpgrade Command-Line Parameters and Options
preupgrade
The AutoUpgrade parameter preupgrade
runs database checks
and preupgrade fixups that fix most issues before you start an upgrade, and postupgrade
fixups that fix most issues after an upgrade is completed.
Property | Description |
---|---|
Parameter type | string |
Syntax |
-preupgrade preupgrade_options -mode [analyze|fixups|postfixups] |
Default value | analyze |
Description
The -preupgrade clause of AutoUpgrade replaces the functions previously preformed
by the manual Pre-Upgrade Information Tool (preupgrade.jar) in previous releases.
The -mode
clause takes one of three values:
analyze
: Check your system for readiness to upgrade.fixups
: Perform fixups as needed on your source Oracle Database release in preparation for upgradepostfixups
: Perform fixups on your target Oracle Database release after upgrade is completed.
If no value for -mode
is specified, then by default the
-preupgrade
parameter defaults to analyze
mode.
Usage Notes
Use the preupgrade
clause only if you want to obtain the same
features previously made available with the Pre-Upgrade Information Tool
(preupgrade.jar
). For most upgrade scenarios, you do not need
to use this parameter.
The -preupgrade
parameter requires
preupgrade_options
, which specifies a list of comma-delimited
option-value pairs in the following format: option1=value1,option2=value2,…
Arguments
-
target_version=release-number
: Specifies the target Oracle Database release version, which is the release to which you want to upgrade.The value for this argument is required by the
analyze
andfixups
modes. However, the target release can be derived fromtarget_home
. Accordingly, foranalyze
andfixups
modes, eithertarget_version
ortarget_home
must be specified. The value fortarget_version
must be12.2
, or a later release value. -
target_home=[target-path|env-variable]
: Specifies the Oracle Database home location of the target release to which you want to upgrade, which can either be the Oracle home path, or an operating system path variable.This argument is mandatory if you select the
postfixups
mode. If you select thepostfixups
mode, and you do not specify a target home path, then the default value is specified by the Oracle home environment variable for the Oracle home set for the user running AutoUpgrade ($ORACLE_HOME
on Linux and Unix systems, or%ORACLE_HOME%
on Microsoft Windows systems). -
oh=[source-path|env-variable]
: Specifies the Oracle Database home location of the source release from which you want to upgrade, which can either be the Oracle home path, or an operating system path variable.This argument is mandatory if you select the
analyze
orfixups
mode. If you select eitheranalyze
orfixups
modes, and you do not specify a source home path, then the default value is specified by the Oracle home environment variable for the Oracle home set for the user running AutoUpgrade ($ORACLE_HOME
on Linux and Unix systems,%ORACLE_HOME%
on Microsoft Windows systems). -
sid=system-identifier
: Specifies an Oracle system identifier for the source database that you want to upgrade. This argument is mandatory foranalyze
orfixups
modes. If you select either theanalyze
or thefixups
mode, and you do not specify a system identifier, then the default value is specified by the Oracle home environment variable for the Oracle home set for the user running AutoUpgrade ($ORACLE_SID
on Linux and Unix systems,%ORACLE_SID%
on Microsoft Windows systems). -
: Directs the output to a specific directory. If you do not specify an output directory with thedir=path
dir
argument, then the output is directed to a folder calledautoupgrade
that is placed in the temporary directory on your system. Typically, that directory is in one of the following locations:- Linux or Unix:
/tmp
, or/var/tmp
. - Microsoft Windows:
C:\WINNT\TEMP
- Linux or Unix:
-
inclusion_list=list
: Specifies a list of pluggable databases (PDBs) inside a container database (CDBs) that you want to include for processing. Provide a space-delimited list of PDBs that you want processed, in one of the following two formats, wherepdb1
,pdb2
, andpdb3
are PDBs that you want processed:pdb1 pdb2 pdb3
(pdb1 pdb2 pdb3)
If you do not specify a list of PDBs, then all PDBs in a CDB are processed.
-
exclusion_list=list
: Specifies a list of pluggable databases (PDBs) inside a container database (CDBs) that you want to exclude for processing. Provide a space-delimited list of PDBs that you want processed, in one of the following two formats, wherepdb1
,pdb2
, andpdb3
are PDBs that you want processed:pdb1 pdb2 pdb3
(pdb1 pdb2 pdb3)
If you do not specify a list of PDBs, then all PDBs in a CDB are processed.
user=username
: Specifies the Oracle Database user name that the AutoUpgrade utility uses to connect to Oracle Database If the user is specified, then AutoUpgrade prompts for the user name password input on the command line. If no user name is specified, then AutoUpgrade uses operating system authentication for the Oracle Database connection.
Modes
-
analyze
(Default value): Runs Autoupgrade in Analyze mode, with all of the preupgrade checks that apply for the target release argument that you specify. If you do not specify a mode, then AutoUpgrade defaults toanalyze
. -
fixups
: Runs preupgrade fixups (when available) for all issues reported by AutoUpgrade Analyze preupgrade checks on the source database that must be fixed before upgrade. All checks are run.Fixup results are reported in the file
upgrade.xml
. That file is placed in the pathlog_dir/db_name/jobnumber/prefixups/prefixups.xml
, wherelog_dir
is the log directory that you specify using thedir
argument,db_name
is the name of the source database, andjobnumber
is the AutoUpgrade job number. -
postfixups
: Runs postupgrade fixups (when available) for all issues reported by AutoUpgrade Analyze preupgrade checks on the upgraded database that you must fix after the upgrade is completed.Postfixup results are reported in the file
postfixups.xml
. That file is placed in the pathlog_dir/db_name/jobnumber/postfixups
, wherelog_dir
is the log directory that you specify using thedir
argument,db_name
is the name of the source database, andjobnumber
is the AutoUpgrade job number.
Examples
Running AutoUpgrade with the preupgrade clause using analyze
mode,
and specifying that the target release is Oracle Database 19c.
java -jar autoupgrade.jar -preupgrade "target_version=19" -mode analyze
Running AutoUpgrade with the preupgrade clause using
fixups
mode, and specifying that the target release is Oracle
Database 19c.
java -jar autoupgrade.jar -preupgrade "target_version=19" -mode fixups
Running AutoUpgrade with the preupgrade clause using
postfixups
mode, and specifying that the target Oracle home is
in the path C:\app\oracle\product\19.0.0\dbhome_1
.
java -jar autoupgrade.jar -preupgrade "target_home=C:\app\oracle\product\19.0.0\dbhome_1" -mode postfixups
Running AutoUpgrade with the preupgrade clause without specifying the
mode, and specifying that the target release is Oracle Database 19c. In this case,
the mode used is the default mode, analyze
.
java -jar autoupgrade.jar -preupgrade "target_version=19"
Parent topic: AutoUpgrade Command-Line Parameters and Options
settings
The AutoUpgrade parameter settings
identifies the configuration file that you use to provide custom runtime configuration of the AutoUpgrade utility.
Property | Description |
---|---|
Parameter type | String |
Syntax | -settings my-custom-advanced-settings |
Default value | Not applicable |
Description
The settings
parameter has the required argument of the name and
path to the settings configuration file, which you have modified with custom
settings. The settings
parameter cannot be used alone, but rather
as a configuration input file that modifies the way that AutoUpgrade runs a
processing mode.
Usage Notes
This parameter is an advanced parameter. For most upgrade scenarios, you should not need to modify any internal AutoUpgrade parameter settings.
Example
In this example, settings specifies a settings input file called my_custom_advanced_settings.cfg.
java -jar autoupgrade.jar -settings my_custom_advanced_settings.cfg -config config.cfg -mode deploy
Parent topic: AutoUpgrade Command-Line Parameters and Options
version
The AutoUpgrade parameter version
prints to the terminal
screen the current build of the autoupgrade.jar
file.
Property | Description |
---|---|
Parameter type | string |
Syntax | -version |
Default value | Not applicable. |
Description
Use this optional parameter to check which version of the autoupgrade.jar utility is on your server.
Usage Notes
Command Example:
java -jar autoupgrade.jar -version
Output example:
[oracle@example ~]$ java -jar autoupgrade.jar -version
build.version 22.1.220304
build.date 2022/03/04 13:29:34 -0500
build.hash 29007da
build.hash_date 2022/03/04 12:48:36 -0500
build.supported_target_versions 12.2,18,19,21
build.type production
Parent topic: AutoUpgrade Command-Line Parameters and Options
restore
The AutoUpgrade parameter restore
performs a system-level
restoration of the AutoUpgrade jobs that you specify.
Property | Description |
---|---|
Parameter type | string |
Syntax | -restore -jobs
job#,job# |
Default value | Not applicable. |
Description
Use this optional parameter to specify a system-level restoration of the jobs you specify, using a comma-delimited list of job numbers. The databases in the upgrade jobs that you specify are flashed back to the Guarantee Restore Point (GRP). Before you run this command, the GRP must have been created by AutoUpgrade.
Examples
java -jar autoupgrade.jar -config config.cfg -restore -jobs 111 java -jar autoupgrade.jar -config config.cfg -restore -jobs 111,222 -console java -jar autoupgrade.jar -config config.cfg -restore -jobs 111,222 -noconsole
Parent topic: AutoUpgrade Command-Line Parameters and Options
restore_on_fail
The AutoUpgrade parameter restore_on_fail
automatically
restores any job that failed during the deployment.
Property | Description |
---|---|
Parameter type | string |
Syntax | -restore_on_fail |
Default value | Not applicable. |
Description
Use this optional parameter to specify that AutoUpgrade restores any jobs that failed during the upgrade deployment.
Examples
java -jar autoupgrade.jar -config config.cfg -mode deploy -restore_on_fail
Parent topic: AutoUpgrade Command-Line Parameters and Options
zip
The AutoUpgrade parameter zip
creates a zip file of log
files required for filing an AutoUpgrade service request.
Property | Description |
---|---|
Parameter type | string |
Syntax |
-zip [-sid sid] [-d dir] [-zip_exclusion_list exclusion_list] |
Default value | Not applicable. |
Description
Use this optional parameter to create a zip file that you can send to Oracle Support
that contains the log files for jobs that are the object of your service request. Use the
-sid
clause to specify a comma-delimited list of system identifiers
(SIDs) of databases whose log files you want to send. If no SID value is defined, then
AutoUpgrade creates a zip file for all databases specified in the configuration file. Use
the -d
clause to specify a specific output directory. If no directory is
specified, then the current directory from which the command is run is used for the zip file
output. Use the -zip_exclusion_list
clause to specify a
double-comma-delimited regular string list that is used to exclude files that match any
regular string from the zip file.
Usage Notes
Note:
When you use the -zip
clause, you cannot use the
-mode
clause.
Examples
java -jar autoupgrade.jar -config yourconfig.cfg -zip
java -jar autoupgrade.jar -config yourconfig.cfg -zip -sid sales1,sales2 -d /scratch/upgrd
java -jar autoupgrade.jar -config yourconfig.cfg -zip
-zip_exclusion_list ".*/db11204/.*"
java -jar autoupgrade.jar -config yourconfig.cfg -zip
-zip_exclusion_list
"/home/oracle/autopatch/DB19X/100/goldimage/db_home_2023-09-21_09-18-13AM.zip,,/home/oracle/autopatch/DB19X/100/extract/35320081/.*"
Parent topic: AutoUpgrade Command-Line Parameters and Options