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.

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

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.

• 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.
• fixed_stats_before
  (Optional) Specifies that AutoUpgrade gathers fixed object statistics on the source database before starting the upgrade.
• rman_catalog_connect_string
  (Optional) Specifies the RMAN connection string used to connect to an RMAN database.
• target_home
  (Required for upgrade and deploy modes, if the target home is not on the system. Optional for analyze and fixups mode.) Specifies the target Oracle home (ORACLE_HOME) path.
• restoration
  (Optional) Generates a Guaranteed Restore Point (GRP) for database restoration.
• source_base
  (Optional) Specifies the source ORACLE_BASE path for the source Oracle home.
• wincredential
  (Optional) Specifies the location of a Microsoft Windows credential object file that you have previously generated with the AutoUpgrade command-line parameter load_win_credential.

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

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

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

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

target_home

(Required for upgrade and deploy modes, if the target home is not on the system. Optional for analyze and fixups mode.) Specifies the target Oracle home (ORACLE_HOME) path.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

Use this option to specify the path to the target database home for the upgrade or patching job. This parameter can overwrite a global target_home setting.

sales1.target_home=/target/Oracle/home

Options

Earlier releases of AutoUpgrade required you to set target_home and target_version. In later releases of AutoUpgrade, this restriction has been lifted for both Analyze and Fixups modes. However, if you don't set target_home, then you must specify target_version. Either one of them must be present.

Example

sales3.target_home=/U01/app/oracle/product/19.0.0/dbhome_1
sales1.target_home=/U01/app/oracle/product/23.0.0/dbhome_1

restoration

(Optional) Generates a Guaranteed Restore Point (GRP) for database restoration.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

If left at default value (yes), a fast recovery area configuration is required to create a GRP. If you set restoration=no, then both the database backup and restoration must be performed manually. Set to no for databases that operate in NOARCHIVELOG mode, and for Standard Edition and Standard Edition 2 databases, which do not support the Oracle Flashback technology feature Flashback Database. If you do not specify the parameter, then the default value (yes) is used, and a guaranteed restore point is created.

Options

[yes | no]

The default value is yes.

Example

sales1.restoration=no

source_base

(Optional) Specifies the source ORACLE_BASE path for the source Oracle home.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

Examples

source_base=/u01/app/oracle
sales4.source_base=/u04/app/oracle4

wincredential

(Optional) Specifies the location of a Microsoft Windows credential object file that you have previously generated with the AutoUpgrade command-line parameter load_win_credential.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

The purpose of this parameter is to create a credentials file to store the user and password credentials for the owner of the Oracle database binaries, and to specify the location of the Administrator PowerShell credential object for those credentials, so that AutoUpgrade can be run using that credential object during the Oracle Database upgrade. 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.

Use case:

You want to specify credentials for the owner of database binaries on a Microsoft Windows server. To specify these credentials, after you enter the wincredential parameter in your configuration file, you run AutoUpgrade in Configuration mode using the load_win_credentials command-line parameter, and provide credentials as prompted. Microsoft Windows Powershell then creates the credential object, and stores the generated credential object in the path location you specify with wincredential. For example, in the following file, the location of the credential file is specified with upg1.wincredential=C:\Users\oracle\cred

Example

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

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

• after_action
  (Optional) In deploy mode, specifies a custom action that you want to have performed after completing the upgrade deploy job for the database identified by the prefix address.
• 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)
• 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.
• create_listener
  (Optional) Creates a listener in the new Oracle home after an upgrade.
• delete_wincredential_file
  (Optional) Deletes the Microsoft Windows credential object file when the AutoUpgrade job is complete.
• 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.
• env
  (Optional) Specifies custom operating system environment variables set on your operating system, excluding ORACLE_SID, ORACLE_HOME, ORACLE_BASE, and TNS_ADMIN.
• log_dir
  (Optional) Sets the location of log files that are generated for database upgrades that are in the set of databases included in the upgrade job identified by the prefix for the parameter.
• revert_after_action
  (Optional) 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, and the database is up.
• 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.
• 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.
• sid
  (Required) Identifies the Oracle system identifier (SID) of the database that you want to upgrade.
• source_home
  (Required for analyze, fixups, and deploy modes. Optional for upgrade mode.) Current Oracle home (ORACLE_HOME) of the database that you want to upgrade or patch.
• source_ldap_admin_dir
  (Optional) Specifies the path to the LDAP_ADMIN directory in the source database home.
• source_tns_admin_dir
  (Optional) Specifies the path to the TNS_ADMIN directory in the source database home.
• start_time
  (Optional) Sets a future start time for the upgrade or patching job to run. Use this parameter to schedule jobs to balance the load on your server, and to prevent multiple jobs from starting immediately.

after_action

(Optional) In deploy mode, specifies a custom action that you want to have performed after completing the upgrade deploy job for the database identified by the prefix address.

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:

The after_action.deploy and after_action.create_home parameters for AutoUpgrade patching and the local parameter after_action 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 after_action parameter, the local after_action 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 postupgrade 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 starts processing, with the Y flag set to stop AutoUpgrade if the script fails:

sales2.after_action=/user/path/script.sh Y 

Run the specified script after AutoUpgrade starts processing, with AutoUpgrade set to continue to run if the script fails:

sales3.after_action=/user/path/script.sh 

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:

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

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 

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.

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:

1. Remove the leading hash symbol (#).

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

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 set delete_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

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

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

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/

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

log_dir

(Optional) Sets the location of log files that are generated for database upgrades that are in the set of databases included in the upgrade job identified by the prefix for the parameter.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

When set, AutoUpgrade creates a hierarchical directory based on a local log file path that you specify. For example, where the job identifier prefix is sales, and where log_dir is identified as upgrade-jobs, and stage1, stage2, and stagen represent stages of the upgrades:

/u01/app/oracle/upgrade-jobs
                                      /temp/
                                      /sales/
                                      /sales/stage1
                                      /sales/stage2
                                      /sales/stagen

You cannot use wild cards for paths, such as tilde (~). You must use a complete path.

Note:

On Microsoft Windows platforms, global.autoupg_log and log_dir should be configured on the same drive.

Example

salesdb.log_dir=/u01/app/oracle/upgrade-jobs

By default, if the global configuration file parameter global.autoupg_log_dir is specified, and you do not specify log_dir, then the default is the path specified in global.autoupg_log_dir.

When neither global.autoupg_log_dir nor log_dir is specified, 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.

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.

revert_after_action

(Optional) 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, 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_after_action runs on the target Oracle home binaries after the restoration process is completed, 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 the revert_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 after AutoUpgrade completes processing the restoration, with the Y flag set to stop AutoUpgrade if the script fails:

sales3.revert_after_action =/user/path/script.sh Y

Run the script you specify on the operating system after AutoUpgrade completes processing the restoration. With no flag, the default stop on fail option is N, so AutoUpgrade continues to run if the script fails:

sales3.revert_after_action =/user/path/script.sh

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 the revert_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

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

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

source_home

(Required for analyze, fixups, and deploy modes. Optional for upgrade mode.) Current Oracle home (ORACLE_HOME) of the database that you want to upgrade or patch.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

For the mode upgrade, the source home and target home values can be the same path.

Example

sales2.source_home=/path/to/my/source/oracle/home

source_ldap_admin_dir

(Optional) Specifies the path to the LDAP_ADMIN directory in the source database home.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

This parameter has no effect on Microsoft Windows, because on Windows, the LDAP_ADMIN environmental variable is set within the registry.

Example

sales1.source_ldap_admin_dir=/u01/app/oracle/12.2/dbhome01/ldap/admin

source_tns_admin_dir

(Optional) Specifies the path to the TNS_ADMIN directory in the source database home.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

This parameter has no effect on Microsoft Windows, because on Windows, the TNS_ADMIN environmental variable is set within the registry.

Example

sales1.source_tns_admin_dir=/u01/app/oracle/12.2/dbhome01/network/admin

start_time

(Optional) Sets a future start time for the upgrade or patching job to run. Use this parameter to schedule jobs to balance the load on your server, and to prevent multiple jobs from starting immediately.

Usage Notes

Note:

This parameter can be used both with AutoUpgrade upgrades and AutoUpgrade patching.

Values must either take the form now (start immediately), or take the English Date Format form DD/MM/YYYY or MM/DD/YYYY, where MM is month, DD is day, and YYYY is year. If you do not set a value, then the default is now.

Permitted values:

now
30/12/2019 15:30:00
01/11/2020 01:30:15
2/5/2020 3:30:50

If more than one job is started with the start_time value set to now, then AutoUpgrade schedules start times based on resources available in the system, which can result in start time for jobs that are separated by a few minutes.

Values are invalid that use the wrong deliminator for the date or time element, or that use the wrong date or hour format, such as the following:

30-12-2019 15:30:00
01/11/2020 3:30:15pm
2020/06/01 01:30:15   

Examples

sales1.start_time=now
sales2.start_time=07/11/2020 01:30:15

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

• after_action
  (Optional) Specifies a path and a file name for a custom user script that you want to have run after all the upgrade jobs finish successfully.
• autoupg_log_dir
  (Deprecated) Sets the location of the log files, and temporary files that belong to global modules, which AutoUpgrade uses.
• before_action
  (Optional) Specifies a custom user script that you want to have run for all upgrades before starting the upgrade jobs.
• global_log_dir
  (Optional) Sets the location of the AutoUpgrade log files, and temporary files that belong to global modules, which AutoUpgrade uses.
• json_progress_writing_interval
  (Optional) Sets the time interval for how often to write the AutoUpgrade progress JSON report.
• keystore
  (Optional) Specifies the location for a dedicated software keystore used exclusively by AutoUpgrade to store passwords, and other sensitive information.

after_action

(Optional) Specifies a path and a file name for a custom user script that you want to have run after all the upgrade jobs finish successfully.

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)

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 postupgrade 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.after_action=/path/to/my/script.sh Y 

If the script fails, then continue AutoUpgrade:

global.after_action=/path/to/my/script.sh

autoupg_log_dir

(Deprecated) Sets the location of the 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 parameters is now deprecated in favor of global_log_dir, which is now used with both AutoUpgrade upgrades and patching.

You can configure different log directory path in the userconfig file in the logs directory for a specific prefix

This parameter cannot be used with AutoUpgrade Patching.

Note:

On Microsoft Windows platforms, global.autoupg_log and log_dir should be configured on the same drive.

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.

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

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

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

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

keystore

(Optional) Specifies the location for a dedicated software keystore used exclusively by AutoUpgrade to store passwords, and other sensitive information.

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 with global.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, replace ORACLE_SID with the system identifier of the database using the keystore.

global.keystore=/etc/oracle/keystores/ORACLE_SID/autoupgrade