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. - 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. - load_password
The AutoUpgrade parameterload_password
enables you to enter passwords safely into AutoUpgrade's keystore. - 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. - 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. - tune_setting
(Optional) Enables special workflows that alter the behavior of AutoUpgrade during runtime, depending on the workflow option that you specify. - 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
-
You must have Java Development Kit (JDK) 8 or later 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.
-
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 fatal, only
errors in |
|
Starts AutoUpgrade with the console enabled. |
|
Starts AutoUpgrade with the console disabled. |
|
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 |
|
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 |
|
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 |
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
two arguments:
-
The configuration file name
-
(Optional) The path to the configuration file, as represented by
config-file
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/21.0.0/
- Microsoft Windows: Equivalent to a
SET ORACLE_TARGET_HOME
command. For example:SET ORACLE_TARGET_HOME=C:\oracle\21
- 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/21.0.0.0/dbhome_1
ORACLE_SID
is set tosales
ORACLE_TARGET_VERSION
is set to21.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/21
# Value from environmental variable ORACLE_SID
autoupgrade1.sid=sales
# Value from environmental variable ORACLE_TARGET_VERSION
autoupgrade1.target_version=21.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/122
autoupgrade1.target_home=/scratch/21
autoupgrade1.sid=sales
autoupgrade2.source_home=/scratch/18
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 reenable or disable the AutoUpgrade console using the option -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.
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 abort queue. |
|
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. |
|
Aborts 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 When you add the
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
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. With
AutoUpgrade 22.1 and later, you can enter Transparent Data Encryption (TDE) keystore
passwords as part of a later database upgrade.
Property | Description |
---|---|
Parameter type | string |
Syntax |
|
Default value | None. AutoUpgrade prompts you for 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. It takes no arguments.
Instead, it starts an interactive prompt with specific commands that enable you to
provide information required for the keystore.
Starting with
AutoUpgrade 22.1, if you do not have an External Password Store, and you use TDE,
then you can use load_password
to load TDE passwords required for
the upgrade.
Note:
If you configure an Keystore External Password Store in the database, then AutoUpgrade detects the presence of an Keystore External Password Store, and use this external password store instead of requiring manual input of the TDE keystore passwords. For more information about Keystore External Password stores, refer to Oracle Database Advanced Security 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_parameter
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. In AutoUpgrade 22.1 and later, the following configuration options are
available:
-
add ORACLE_SID
Adds a TDE password for the specified Oracle System identifier (
ORACLE_SID
) -
delete ORACLE_SID
Deletes a loaded 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. -
group
Changes the password group being processed. With AutoUpgrade 22.1, Transparent Data Encryption (TDE) is the only group option.
-
save
Saves the keystore to the location specified by the
global.keystore
directory. If an auto-login keystore is not already enabled, then you are prompted whether you want to convert the keystore to an auto-login keystore. -
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. 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.
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
source databases:
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> group other
No support for group [other] - Available groups [TDE]
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
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
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 21c.
java -jar autoupgrade.jar -preupgrade "target_version=21" -mode analyze
Running AutoUpgrade with the preupgrade clause using
fixups
mode, and specifying that the target release is Oracle
Database 21c.
java -jar autoupgrade.jar -preupgrade "target_version=21" -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\21.0.0\dbhome_1
.
java -jar autoupgrade.jar -preupgrade "target_home=C:\app\oracle\product\21.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 21c. In this case,
the mode used is the default mode, analyze
.
java -jar autoupgrade.jar -preupgrade "target_version=21"
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
tune_setting
(Optional) Enables special workflows that alter the behavior of AutoUpgrade during runtime, depending on the workflow option that you specify.
Usage Notes
The tune_setting
parameter enables you to fine-tune
upgrade steps or the resources allocated to the processing of the upgrades specified
by the container databases or pluggable databases (CDBs or PDBs) specified by the
parameter prefix in your AutoUpgrade configuration file. This capability can be
useful for some upgrades if you find the default AutoUpgrade values are insufficient
for your system requirements, or when you want to enable nondefault AutoUpgrade
options.
Syntax
prefix.tune_setting=option[, option, option, ...]
Select
the tune_setting
options that provide the AutoUpgrade runtime tuning
that you require from the list that follows. To combine multiple tuning options with the
tune_setting
parameter, use comma delimiters. Example:
sales3.tune_setting=proactive_fixups=true,query_hint_parallel=8,utlrp_threads_per_pdb=8
Note:
You can concatinate multiple parameters together in a singletune_setting
entry
Option | Description |
---|---|
active_nodes_limit |
Sets a new total of active cluster member nodes that you want to use during a distributed upgrade of Oracle Real Application Clusters databases. The default is 2. If the number you specify is equal to or greater than the maximum number of cluster member nodes, then all nodes are taken.
|
distributed_upgrade |
Specifies that AutoUpgrade performs a distributed
upgrade. A distributed upgrade leverages the
resources of the Oracle Clusterware cluster member nodes to
perform the upgrades of PDBs more rapidly on the cluster. Use
this option when a CDB in an Oracle RAC cluster of at least two
nodes is being upgraded. When you choose this option, the
|
make_pdbs_available |
Opens the PDBs designated by the prefix in read/write and non-restricted mode after postfixups are complete when proactive fixups mode is used. This option enables PDBs designated by the prefix to become available for service immediately after the upgrade is completed, while other PDBs continue to be upgraded, which can be useful for large fleet upgrade deployments. Precautions: Choosing this option enables the PDBs you designate to accept service requests from users, while other PDBs are being upgraded. The response time of the PDBs for service requests, and the time required for ongoing PDB upgrades can each be affected. Example:
|
proactive_fixups |
Enables proactive fixups mode, where the PDBs are upgraded as the last stage of the upgrade. When the number of PDBs is higher than the CPU count defined in the database, divided by 2, choosing this tuning option can result in a faster upgrade. Example:
Precautions: If the number of CPUs is higher than the number of PDBs, then changing this setting may not improve performance. |
query_hint_parallel |
Specifies a parallel thread specification to the code that gathers data from the tablespaces during the query of the PDBs specified by the prefix, so that you can allocate a greater number or lesser number of parallel threads to the PDBs specified by the prefix. Example:
Choosing this option can cause AutoUpgrade to consume more system resources. |
utlrp_threads_per_pdb |
Overwrites default maximum number of threads generated by the recompilation of invalid objects in the CDB, and uses the number of threads that you specify. Example:
Precautions: If the number of threads specified exceeds available threads on the system, then performance can be compromised. |
utlrp_pdb_in_parallel |
Overwrites default maximum number of concurrent recompilation threads to the number that you specify. Use this option to overwrite the default maximum number of concurrent processes of recompilation of invalid objects. Example:
Precautions: Each PDB process requires from the system as many threads as
specified by |
Examples
sales3
are Oracle Real Application Clusters Oracle Database
instances. The tune_setting
parameter is used to set these database
instances to use the setting distributed_upgrade
, which distributes
the upgrade load across multiple CDBs in the Oracle Grid Infrastructure cluster:
sales3.tune_setting=distributed_upgrade=true
In the following
example, the database upgrades specified with the prefix sales3
are
tuned with multiple tune_setting
parameter options:
sales3.tune_setting=proactive_fixups=true,query_hint_parallel=8,utlrp_threads_per_pdb=8
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] |
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.
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
Parent topic: AutoUpgrade Command-Line Parameters and Options