Creating a Database Deployment Using a Cloud Backup

You can create an Oracle Database Exadata Cloud at Customer database deployment whose database is instantiated from a cloud backup created using Oracle Database Backup Cloud Service.

This technique is called instantiate-from-backup and the database that is the origin of the backup is called the source database. Instantiate-from-backup can be used in the following ways:

You can use the Create Instance wizard to perform an instantiate-from-backup operation during the creation of a new database deployment. See Creating a Database Deployment.
Alternatively, you can use the instantiate-from-backup function to replace the database associated with an existing database deployment. See Replacing the Database by Using the Oracle Database Cloud Service Console and Replacing the Database by Using ibkup Actions.

In any case, the source database backup must meet certain suitability requirements. These include:

If the source database is from an existing database deployment, ensure that the database deployment has been backed up to cloud storage. For more information, see About Backing Up Database Deployments on Exadata Cloud at Customer.
If the source database is an on-premises Oracle database, ensure that the database is suitable for instantiation in the cloud and then create a cloud backup. For instructions, see Creating a Cloud Backup of an On-Premises Database.
The source database backup must use Oracle Database version 18, 12.2.0.1, 12.1.0.2, or 11.2.0.4 with the latest patch set update (PSU) applied.
If the source database uses Oracle Database version 12.1.0.2, or later, it must be a multitenant container database (CDB). Exadata Cloud at Customer does not support non-CDB databases for Oracle Database 12c, or later.
The source database uses File System or ASM as its storage method for data files.

After completing an instantiate-from-backup operation, the resulting database deployment exhibits the following characteristics:

The database uses the SID that you specified when creating the database deployment.
The database files and data are from the source database backup.
The database identifier (dbid value in V$DATABASE) will be different from the source database identifier.
The Oracle Net listener is configured with services for the database, and PDBs if applicable.

Creating a Cloud Backup of an On-Premises Database

Use the ibackup utility to create a backup of an on-premises Oracle Database, which can then be used to replace an Oracle Database Exadata Cloud at Customer database.

The ibackup utility enables you to:

Perform a pre-check of the on-premises database to ensure that you can generate a backup that is suitable for replacing a cloud database.
Generate an Oracle Database backup, as well as additional files, that you can use to replace the database on an Exadata Cloud at Customer database deployment as part of an instantiate-from-backup operation.

Prerequisites

Ensure that the on-premises database you intend to back up, as well as the Exadata Cloud at Customer database you intend to replace, meet the requirements described in Creating a Database Deployment Using a Cloud Backup.

The source on-premises database must also meet the following additional criteria:

The on-premises database host must be a Linux X64 (OEL 6 or OEL 7) system.
The database character set of your on-premises database must be compatible with the Exadata Cloud at Customer database that you intend to replace.
Non-Oracle software on the on-premises database host must meet the following minimum release requirements:
- Java: Release 7 or higher. Java must be in the default path.
- Python: Above Release 2.6 and below Release 3.0.

Procedure

Perform these tasks:

Download a zip file containing the ibackup utility to the on-premises database host. Use wget on the on-premises database host to download the OracleCloud_ibackup_Setup.zip file from Oracle Cloud Infrastructure Object Storage Classic:
```
$ wget https://storage.us2.oraclecloud.com/v1/dbcsswlibp-usoracle29538/ibackup/OracleCloud_ibackup_Setup.zip
```
On the on-premises database host:
1. Log in as the oracle user.
2. Unzip the OracleCloud_ibackup_Setup.zip file. Files are extracted into the ibackup directory.
3. Switch to the root user and run the following command to set the ownership of the files in the ibackup directory:
```
# chown -R oracle:oinstall ibackup
```
4. Return to being the oracle user and navigate to the ibackup directory:
```
$ cd ibackup
```
5. Edit the backup.cfg file as follows:
  - Set the encryption mode for the database backup. Set TDE=y if the database uses Transparent Data Encryption. Set TDE=n to use RMAN key encryption.
  - Set the value for target_db to 18.0.0, 12.2.0.1, 12.1.0.2, or 11.2.0.4, depending on the version of the Exadata Cloud at Customer database deployment where you intend to instantiate the backup.
  - Set the value for oss_user to the user name of a user who has read/write access to the storage container specified in oss_url.
  - Set the value for oss_url to the URL of the Oracle Cloud Infrastructure Object Storage Classic container that will be used to store the database backup.
  - You can set the value for oss_url to the password of the user specified in oss_user. If you specify a value for oss_passwd, the password is obfuscated the first time you run the ibackup tool. If you do not enter a password value, you are prompted for the password when you run the tool.
  - If you set TDE=n, set the rman_key value to the RMAN encryption key. Otherwise, leave this value blank.
Run a pre-check on the source on-premises database. The pre-check does not generate a backup file.
```
$ ./ibackup -d dbname
```
In the above command, dbname is the name of the source database. Examine the pre-check results.
Generate a backup:
```
$ ./ibackup -d dbname -b -i
```
Optionally, you can use the —f option to ignore fix-up log failures when generating a backup:
```
$ ./ibackup -d dbname -b -i -f
```
In addition to the Oracle Database backup, the following files are also generated in the /var/opt/oracle/ibackup/ibkup directory:
- tde_wallet.zip — The TDE wallet directory. This file is generated only if TDE was enabled in the on-premises database. Copy this file to a secure and accessible location. This file is required to import the Oracle backup in an instantiate-from-backup operation.
- TDE_README.txt — Instructions on how to unzip the tde_wallet.zip file. This is important because the instantiate-from-backup operation expects a defined structure for the TDE wallet directory.
- Import.json — Template file to import the backup using ibkup actions with the dbaasapi utility.
- oss_file.cfg — Oracle Cloud Infrastructure Object Storage Classic information used to save the backup.
Use these files when replacing the database on an Exadata Cloud at Customer database deployment as part of an instantiate-from-backup operation.

Replacing the Database by Using the Oracle Database Cloud Service Console

You can use the Oracle Database Cloud Service console to replace the database for an Exadata Cloud at Customer database deployment using an instantiate-from-backup operation.

Before You Begin

If you wish to replace your database using a backup from another currently operational Exadata Cloud at Customer database deployment in the same identity domain, then you must specify the source database deployment by selecting from a list of the available deployments.

If you wish to replace your database using any other backup, you are prompted for the following information:

The database ID of the backed-up database.
The decryption method for the backup, which is the password associated with the backup for backups that use password encryption, or a zip file containing the source database’s wallet directory and contents for backups that use Transparent Data Encryption (TDE).
The name of the Oracle Cloud Infrastructure Object Storage Classic container where the backup is stored.
The user name and password of an Oracle Cloud user who has read access to the container.

Procedure

Open the Instances page of the Oracle Database Cloud Service console.

For detailed instructions, see Accessing the My Services Dashboard and the Oracle Database Cloud Service Console.
Click the database deployment whose database you wish to replace.

The Oracle Database Cloud Service Overview page is displayed.
From the action menu () next to the database deployment name, choose Replace Database using Backup.

The Replace Database using Backup window is displayed.
Specify attributes in the Replace Database using Backup window:

On-Premises Backup? — use this option to indicate the origin of the source database backup.

If you select this option you are indicating that the source database backup is not from another currently operational Exadata Cloud at Customer database deployment in the same identify domain. In this case, the following fields and options are displayed:
- Database ID — enter the database id of the database from which the existing backup was created. You can get this value by querying the backup source database as follows:
```
SQL> SELECT dbid FROM v$database;
```
- Decryption Method — provide the information necessary to decrypt the existing backup:
  - For a backup that uses Transparent Database Encryption (TDE), select Upload Wallet File then click Browse and specify a zip file containing the source database’s TDE wallet directory, and the contents of that directory.
    
    Note:
    If the source database is from another Exadata Cloud at Customer database deployment, its TDE wallet directory is /u02/app/oracle/admin/dbname/tde_wallet or /var/opt/oracle/dbaas_acfs/dbname/tde_wallet.
  - For a backup that uses password encryption, select Paste RMAN Key Value and paste the password (key value) used to encrypt the backup.
  Note:
  For database deployments using Oracle Database 12c Release 2 (12.2), or later, only backups using TDE are supported.
- Cloud Storage Container — enter the name of the Oracle Cloud Infrastructure Object Storage Classic container where the existing backup is stored; use this format:
```
instance-id_domain/container
```
  where instance is the name of the Oracle Cloud Infrastructure Object Storage Classic instance, id_domain is the id of the identity domain, and container is the name of the container.
- Username — enter the user name of an Oracle Cloud user who has read access to the container specified in Cloud Storage Container.
- Password — enter the password of the user specified in Username.
- Administration Password and Confirm Password — enter and then re-enter a new administration password.
  
  The administration password is used to configure administration accounts and functions in the database deployment, including the password for the Oracle Database SYS and SYSTEM users in the newly replaced database.
  
  Note:
  Ensure that you remember the administration password associated with your database deployment.
If you deselect On-Premises Backup? you are indicating that the source database backup is from another currently operational Exadata Cloud at Customer database deployment in the same identity domain. In this case, the following fields are displayed:
- Source Instance Name — specify the database deployment whose database backup you want to use.
- Backup Tag — a list of backups available for the specified database deployment.
- Administration Password and Confirm Password — enter and then re-enter a password for the Oracle Database SYS and SYSTEM users in the newly replaced database.
Click Replace Database and confirm that you want to replace the database when prompted.

The database deployment is put into Maintenance status and the operation begins. The process is fully automated and takes some time to complete. You should not access or manipulate the database deployment until the process is completed.

Replacing the Database by Using `ibkup` Actions

You can perform an instantiate-from-backup operation by using ibkup actions with the dbaasapi utility to replace the existing database in an Exadata Cloud at Customer database deployment with a database sourced from a cloud backup.

The dbaasapi utility operates by reading a JSON file containing instructions and other information and writing its results to a JSON file specified in the input file. In essence, it is a command-line utility that operates like a REST API endpoint, accepting a JSON request body and producing a JSON response body. The dbaasapi utility checks that the operation being requested does not conflict with any operation already in progress and then runs the operation asynchronously: that is, it starts the requested operation and then returns terminal control to you.

Here are the tasks you perform to replace the database by using ibkup actions:

Copy the TDE wallet from the source database to the Exadata Cloud at Customer deployment, if necessary.
Create dbaasapi input files for ibkup begin and ibkup status actions.
Run the ibkup begin action.
Run the ibkup status action to monitor progress of the ibkup operation.
Upon completion of the ibkup operation, confirm that the source database now resides on the Exadata Cloud at Customer deployment.

Copy the Source Database TDE Wallet

If the cloud backup you are using was created using Transparent Data Encryption (TDE) or dual-mode encryption, you need to copy the TDE wallet from the source database to the database deployment.

Note:

If the source database is from another Exadata Cloud at Customer database deployment, its backup was created using Transparent Data Encryption (TDE). All cloud backups from Exadata Cloud at Customer use TDE as the backup encryption mode.

On an Exadata Cloud at Customer compute node that is associated with your target database deployment, connect as the oracle user and create a directory to store the source database TDE wallet along with other files that you create in later steps. For example:
```
$ mkdir –p /home/oracle/ibkup  
```
Copy the source database's tde_wallet directory to the newly created directory.

If the source database is from another Exadata Cloud at Customer database deployment, its tde_wallet directory is located at /u02/app/oracle/admin/dbname/tde_wallet or /var/opt/oracle/dbaas_acfs/dbname/tde_wallet, where dbname is the name of the database. You can find the location of the tde_wallet directory by querying V$ENCRYPTION_WALLET.

Ensure that the tde_wallet files are owned by oracle and only accessible by oracle. For example:

$ chown -R oracle:oinstall /home/oracle/ibkup/tde_wallet
$ chmod 600 /home/oracle/ibkup/tde_wallet/*

Create dbaasapi Input Files

Use a secure shell utility like SSH or PuTTY to connect as the opc user to the compute node that is associated with your target database deployment. For instructions, see Connecting to a Compute Node Through Secure Shell (SSH).
The dbaasapi utility must be run as the root user. Start a root-user shell:
```
$ sudo -s 
# 
```
Navigate to the directory where you previously stored the source database TDE wallet.
```
# cd /home/oracle/ibkup
```
If you did not copy the source database TDE wallet, create a directory to store your request and response files and then navigate to it.

Create a begin-request.json file to pass to dbaasapi to perform the ibkup begin action.

Here is an example that uses a password-encrypted backup:

# cat begin-request.json 
{
  "object": "db",
  "action": "begin",
  "operation": "ibkup",
  "params": {
    "dbname": "crmdb",
    "dbid": "1428538966",
    "oss_url": "https://mystore.storage.oraclecloud.com/v1/Storage-mystore/IBKUP",
    "oss_user": "storageadmin",
    "oss_passwd": "pa55word",
    "decrypt_key": "backup",
    "passwd": "Welcome-1",
    "dbsize": "30GB"
  },
  "outputfile": "/home/oracle/ibkup/begin-response.json",
  "FLAGS": ""
}

The JSON object for the ibkup begin action supports the following parameters. All parameters are required unless identified as optional.

Parameter	Description
`object`	The value `"db"`.
`action`	The value `"begin"`.
`operation`	The value `"ibkup"`.
`params`	An object containing parameters that provide details for the `ibkup begin` action. This object has the following parameters: `dbname`: The name of the target database that you are replacing. You can get this value by querying the target database: SQL> SELECT name FROM v$database; `dbid`: The database id of the source database. You can get this value by querying the source database: SQL> SELECT dbid FROM v$database; `oss_url`: The URL of the container that stores the source database's backup. `oss_user`: The user name of an Oracle Cloud user who has read privileges for the container that stores the source database's backup. `oss_passwd`: The password of the `oss_user` user. `rman_handle`: (Optional) The RMAN handle of a targeted backup that contains controlfile and spfile backups. The `ibkup begin` action uses the controlfile and spfile in this backup. Use the `rman_tag` parameter to specify the RMAN tag of a backup supported by this controlfile and spfile. If you do not specify an RMAN tag, the latest backup supported by this controlfile and spfile is used. Oracle recommends that you provide both a handle and a tag to use a specific backup or provide no handle and no tag to use the latest backup. You can view RMAN handles and tags by using the RMAN `LIST BACKUP` command. `rman_tag`: (Optional) The RMAN tag of a targeted full backup. The `ibkup begin` action uses this backup. Use the `rman_handle` parameter to specify the RMAN handle of a backup containing controlfile and spfile backups that support this RMAN tag. If you do not specify an RMAN handle, the latest controlfile and spfile are used. If the RMAN handle does not support the specified RMAN tag, a `datafile not found` error occurs. Oracle recommends that you provide both a handle and a tag to use a specific backup or provide no handle and no tag to use the latest backup. You can view RMAN handles and tags by using the RMAN `LIST BACKUP` command. `decrypt_key`: (Optional) The key (password) used to encrypt the backup. Provide this parameter if you created the backup using password encryption or dual-mode encryption. Note: you cannot use this option when replacing the database on a database deployment using Oracle Database 12c Release 2 (12.2) or later, because only backups using TDE are supported for such deployments. `decrypt_wallet`: (Optional) The fully qualified path of the wallet directory you copied from the source database to the DBCS deployment you created; for example: `/home/oracle/ibkup/tde_wallet`. Provide this parameter if you created the backup using Transparent Data Encryption (TDE) or dual-mode encryption. `passwd`: The administrator (SYS and SYSTEM) password to use for the target database after the replacement operation concludes. `dbsize`: The size of the source database. For Exadata Cloud at Customer, provide an estimate of the source database size.
`outputfile`	The fully qualified name of the output file for `dbaasapi` to use; for example: `"/home/oracle/ibkup/begin-response.json"`.
`FLAGS`	The value `""` (an empty string).

Create a status-request.json file to pass to dbaasapi to perform the ibkup status action. Here is an example:

# vim status-request.json
{
  "object": "db",
  "action": "status",
  "operation": "ibkup",
  "id": "TBD",
  "params": {
    "dbname": "crmdb"
  },
  "outputfile": "/home/oracle/ibkup/status-response.json",
  "FLAGS": ""
}

In this example, the value of the id parameter is "TBD" because the corresponding ibkup begin action has not been run yet.

The JSON object for the ibkup status action supports the following parameters. All parameters are required.

Parameter	Description
`object`	The value `"db"`.
`action`	The value `"status"`.
`operation`	The value `"ibkup"`.
`id`	The ID number of the action you want status for.
`params`	An object containing parameters that provide details for the `ibkup status` action. This object has the following parameters: `dbname`: The name of the database on the target database that is being replaced.
`outputfile`	The fully qualified name of the output file for `dbaasapi` to use; for example: `"/home/oracle/ibkup/status-response.json"`.
`FLAGS`	The value `""` (an empty string).

Run the ibkup begin Action

Use dbaasapi to run the ibkup begin action:

# /var/opt/oracle/dbaasapi/dbaasapi -i begin-request.json

View the output file to confirm that the action has started and note the id of the action; for example:

# cat /home/oracle/ibkup/begin-response.json 
{
   "msg" : "",
   "object" : "db",
   "status" : "Starting",
   "errmsg" : "",
   "outputfile" : "",
   "action" : "begin",
   "id" : "19",
   "operation" : "ibkup",
   "logfile" : "/var/opt/oracle/log/crmdb/dbaasapi/db/ibkup/19.log"
}

The key parameters in this response are as follows:

Parameter	Description
`status`	The status of the operation; one of: `"Error"`, `"Starting"`, `"InProgress"` or `"Success"`.
`action`	The value `"begin"`, which is the `ibkup` action you requested.
`id`	The ID number assigned to this action. Use this number in subsequent `ibkup status` actions to check the status of the overall `ibkup` operation.
`operation`	The value `"ibkup"`, which is the operation you requested.
`logfile`	The log file for the `ibkup` operation. You can poll this log file to monitor progress of the operation. However, you should run the `ibkup status` action to monitor progress because it provides extra status information along with a definitive indication of when the operation is finished.

Run the ibkup status Action to Monitor Progress

Update the status-request.json input file with id value of the ibkup operation that you have started. Edit the status-request.json file, replacing the id parameter value of "TBD" with the ID number reported in the begin-response.json file.

Use dbaasapi to run the ibkup status action and view the response; for example:

# /var/opt/oracle/dbaasapi/dbaasapi -i status-request.json
# cat status-response.json
{
   "msg" : "  -> 15 03 * * 6 oracle /var/opt/oracle/cleandb/cleandblogs.pl\\n\\n#### Completed OCDE Successfully ####",
   "object" : "db",
   "status" : "Success",
   "errmsg" : "",
   "outputfile" : "",
   "action" : "begin",
   "id" : "19",
   "operation" : "ibkup",
   "logfile" : "/var/opt/oracle/log/crmdb/dbaasapi/db/ibkup/19.log"
}

Rerun the ibkup status action regularly until the response indicates that the operation is finished.

Confirm Successful Completion

Confirm successful completion of the instantiate-from-backup operation by connecting to the replacement database and verifying that it contains the expected structure and data. For example, you could query V$PDBS to ensure that the database contains the expected PDBs, or you could query a specific application table to ensure that it contains the expected data. Also ensure that the expected database instances are up and running.

Connect as the oracle user to a compute node that is associated with your target database deployment.

See Connecting to a Compute Node Through Secure Shell (SSH).
Configure the Oracle Database environment variable settings:
```
$ . oraenv
```
Ensure that of the expected database instances are running:
```
$ srvctl status database -d dbname
```
Connect to the replacement database and confirm that it contains the expected structure and data.

For example, you could query V$PDBS to ensure that the database contains the expected PDBs:
```
$ sqlplus / as sysdba
SQL> select name, open_mode, restricted from v$pdbs;
```
Check that services registered with the Oracle Net Listener include the services from the source database:
```
$ lsnrctl status
```

More About ibkup Actions

The preceding instantiate-from-backup tasks showed the use of two ibkup actions; begin and status. Here is more information about what these two actions do, along with information about two other ibkup actions; prereqs and restore.

The begin action:
1. Validates the format and completeness of the input file.
2. Creates the output file, which includes an ID number for use in subsequent status actions.
3. Releases terminal control.
4. Performs the same value-validation checks that the prereqs action performs.
5. Takes a backup of the current database deployment environment, should the need arise to restore the environment after a failed ibkup operation.
6. Replaces the current database using the backup of the source database.
The status action:
1. Validates the format and completeness of the input file.
2. Retrieves the current status of operation whose ID number was provided in the input file.
3. Creates the output file, which contains the retrieved status information.
The prereqs action takes an input file of the same format as the begin and restore actions, except that the value of the action parameter must be "prereqs".

You can use the prereqs action to test whether the input file you intend to use for either the begin action or the restore action is valid and that the backup specified in the file is available.

The prereqs action does as follows:
1. Validates the format and completeness of the input file.
2. Creates the output file, which includes an ID number for use in subsequent status actions.
3. Releases terminal control.
4. Checks that the values provided in the input file would be valid if used in the input file for a begin or restore action. It confirms access to the backup, including use of the decryption key and wallet as necessary, and that the backup's database ID matches the provided dbid.
The restore action takes an input file of the same format as the begin action, except that the value of the action parameter must be "restore".

If a begin operation fails, you can use the restore action to reset the database deployment's environment so that you can attempt the begin operation again, after determining the cause of the failure and correcting the problem.

After you use the restore action, you need to reboot the compute nodes that are associated with the database deployment to ensure that the environment is completely reset. For instructions, see Stopping, Starting, and Restarting Compute Nodes.

The restore action does as follows:
1. Validates the format and completeness of the input file.
2. Creates the output file, which includes an ID number for use in subsequent status actions.
3. Releases terminal control.
4. Terminates any begin action that is in progress.
5. Kills all processes related to the begin action. If it cannot kill one or more processes, it exits with an error status.
6. Restores the database deployment environment to its state before the first begin action.

Creating a Cloud Backup of an On-Premises Database

Replacing the Database by Using the Oracle Database Cloud Service Console

Replacing the Database by Using ibkup Actions

Replacing the Database by Using `ibkup` Actions