Template script workflow

The following workflow describes the steps that the template script performs and how it uses the Phoenix Backup Store API to backup Oracle databases. This workflow is described using the following example scenario:

• RMAN host is a Linux server.
• The IP address of the Phoenix Backup Store is 192.0.2.1
• The name of the backup mount on the Phoenix Backup Store is testmount. 
• The backup mount called testmount on the Phoenix Backup Store is mapped to the /local/testmount folder on the RMAN host.
• The RMAN logs are stored in the directory:  /home/test-usr/rman-log-directory.
• The template Linux script that Druva provides to back up databases is run as:

  ./oracle_rman_data_backup.sh /home/test-usr/rman-log-directory 192.0.2.1 testmount
  

The following procedure describes the template script workflow:

1. The script makes a GET request to the Phoenix Backup Store to get the status of the backup mount. For example:

   curl -X GET http://192.0.2.1:9090/druva-phoenix/v1/mounts/testmount/backup 2> /dev/null
   

2. The Phoenix Backup Store returns a JSON object. For example:  

   {
       "error_code": 0,   
       "error_msg": “”,
       "result": {
           "mount_name": "testmount", 
           "is_reached_max_snapshots": false,
       }
   }

   This is a sample response that the script receives if there is no issue with the backup mount. If there is no issue with the backup mount, then RMAN can start a database backup. The JSON object is returned with an error if there is an issue with the Phoenix Backup Store. Druva recommends that the next step is not performed if "is_reached_max_snapshots" is returned as true. In template script workflow, the script execution stops if "is_reached_max_snapshots" is returned as true.

3. The script makes a POST request to the Phoenix Backup Store. Based on the response, it runs RMAN commands to start the database backup and write the backup data on the backup mount. For example:

   curl -X POST http://192.0.2.1:9090/druva-phoenix/v1/mounts/testmount/backup 2> /dev/null
   

4. The Phoenix Backup Store returns a JSON object. For example:  

   {
       "error_code": 0,   
       "error_msg": “”,
       "result": {
           "mount_path": "/Phoenix/testmount/oracle_data",
           "mount_name": "testmount", 
           "mount_params": {“timeo”:1200, “retrans”:5},
       }
   }
   

   This is a sample response that the script receives if there is no issue with the backup mount, and then runs RMAN commands that:

   • Start Oracle database backup
   • Write the backup data to the mount

   The JSON object is returned with an error if there is an issue with the backup mount or with the Phoenix Backup Store configuration.

5. The script makes the following POST request after:
   • The RMAN commands are run
   • The Oracle RMAN backup is written to the backup mount
   • Execution control returns to the script

   The script makes this request to notify Phoenix Backup Store to upload the RMAN  logs to the Druva Cloud along with the snapshot of the Oracle RMAN backup. For example: 

   curl -X POST -H "Content-Type: multipart/form-data" -F "file=/home/test-usr/rman-log-directory/rman_full_backup_$file_stamp.log" -F mountpoint=/local/testmount -F platform=linux http://192.0.2.1:9090/druva-phoenix/v1/mounts/testmount/uploadlog 2> /dev/null
   

6. The Phoenix Backup Store returns a JSON object. For example:

   {
       "error_code": 0,
       "error_msg": “”,
       "result": {
           "mount_name": "testmount",
        }
   }
   
   

   This is a sample response that the script receives if there is no issue with the backup mount or the Phoenix Backup Store. The JSON object is returned with an error if there is an issue with the backup mount or with the Phoenix Backup Store configuration. If you are using a custom script, this API request is optional. However, Druva recommends using this API request since this request lets Druva map a database to its files in the Oracle RMAN backup. The mapping between a database and its file is useful when an administrator runs a restore job. If this mapping is available, the administrator can see files in a database and additional files backed up. 

7. After the request to upload RMAN logs is successful, the script makes a PUT request to notify the  Phoenix Backup Store that the Oracle RMAN backup was written successfully to the backup mount and it can upload the snapshot to the Druva Cloud. For example:

   curl -X PUT http://192.0.2.1:9090/druva-phoenix/v1/mounts/testmount/backup 2> /dev/null
   

8. The Phoenix Backup Store returns a JSON object. For example:

   {
       "error_code": 0,
       "error_msg": "",
       "result": {
           "snap_name": "UID_1",
           "mount_name": "testmount",
        }
   }
   

   This is a sample response that the script receives if there is no issue with the backup mount or Phoenix Backup Store after RMAN completes writing Oracle RMAN backup successfully. The successful PUT request also updates the Phoenix Backup Store services to create a ZFS snapshot of the Oracle RMAN backup and upload the snapshot to the Druva Cloud. The JSON object is returned with an error if there is an issue with the backup mount or with the Phoenix Backup Store configuration.

9. After the Oracle RMAN backup is written successfully on the Phoenix Backup Store, the PUT request updates Phoenix Backup Store services that:
   • Create a ZFS snapshot of the Oracle RMAN backup.
   • Apply the time-stamp of the PUT request to the snapshot.
   • Upload the snapshot to the Druva Cloud. The snapshot serves as a snapshot, and it is retained on the Druva Cloud based on the retention policy.

Note: The Phoenix Backup Store deletes the ZFS snapshot after it successfully uploads it to the Druva Cloud.

In addition to the API requests listed above, Phoenix Backup Store provides one more API call that a Database Administrator can use to delete the data downloaded from the Druva Cloud. 

When a snapshot is downloaded from the Druva Cloud:

• It is unpacked and downloaded as an Oracle RMAN backup
• It is downloaded to a location on the Phoenix Backup Store.

This Oracle RMAN backup is restored to the Oracle instance. After it is restored to the Oracle instance, the Database Administrator can choose to remove its data from the Phoenix Backup Store. To remove the data, make a DELETE request to the Phoenix Backup Store with its location. For example:

curl -X DELETE http://192.0.2.1:9090/druva-phoenix/v1/mounts/testmount/restores/242135

The Phoenix Backup Store returns the following JSON object if the folder and the directory is successfully deleted:

{
    "error_code": 0,
    "error_msg": "",
    "result": {
        "mount_name": "testmount",
        "jobid": 242135
     }
}

If the delete operation fails, the JSON object is returned with an error.

API Errors

Following table provides the errors that are returned with the JSON object if an API request fails:

Error code	Issue with	Message	Cause
4295622675	Phoenix Backup Store	Store Decommission in progress.	Phoenix Backup Store is waiting to get disabled.
4295622676	Phoenix Backup Store	Store was decommissioned.	Phoenix Backup Store is disabled.
4295622665	Backup Mount	Backup mount does not exist on Export Service.	Backup mount is not created successfully on the Phoenix Backup Store.
4295622669	Backup Mount	Backup mount is inconsistent state on Export Service.	Possible reasons: Backup mount is not created on the Phoenix Backup Store completely ZFS custom properties were changed
4295622667	Backup Mount	Backup mount marked for delete on Export Service.	Backup mount is getting deleted.
4295622670	RMAN backing up data	Failed to export path to NFS.	Druva internal error.
4295622659	RMAN writing backup data to backup mount	START_BACKUP cmd not received yet.	PUT request to the API was made before the POST request.
4295622664	RMAN writing backup data to backup mount	Backup mount exceeded max pending snapshots.	RMAN cannot write a new Oracle RMAN backup to the backup mount if the number of snapshots that exist on a backup mount exceeds a certain limit.  Phoenix Backup Store can delete the snapshots only after the snapshots are uploaded to the cloud.
4295622663	Deleting Oracle RMAN backup downloaded from Druva Cloud	Restore Path is missing on Export Service.	Possible reasons: Restore path does not exist Restore path is not exposed to NFS