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 recovery point 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 recovery point 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 recovery point of the Oracle RMAN backup and upload the recovery point 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 recovery point of the Oracle RMAN backup.
   • Apply the time-stamp of the PUT request to the recovery point.
   • Upload the recovery point to the Druva Cloud. The recovery point serves as a recovery point, and it is retained on the Druva Cloud based on the retention policy.

Note: The Phoenix Backup Store deletes the ZFS recovery point 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 recovery point 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	Resolution
4295622675	Phoenix Backup Store	Store Decommission in progress.	Phoenix Backup Store is waiting to get disabled.	Wait for the Phoenix Backup Store to get in the disabled state. If the Phoenix Backup Store does not get disabled, contact Support. Once it is disabled, to take a backup, reregister the Phoenix Backup Store and restart the Phoenix Backup Store service.
4295622676	Phoenix Backup Store	Store was decommissioned.	Phoenix Backup Store is disabled.	Once disabled, to take backup, reregister the Phoenix Backup Store and restart the Phoenix Backup Store service.
4295622665	Backup Mount	Backup mount does not exist on Export Service.	Either the backup mount name is incorrect, or the IP for Phoenix Backup Store is incorrect.	Mount names are case-sensitive. Make sure you provide a correct name for the backup mount. Also, use the correct IP for the Phoenix Backup Store.
4295622669	Backup Mount	Backup mount is inconsistent state on Export Service.	The following are the possible causes: Backup mount is not created on the Phoenix Backup Store completely ZFS custom properties were changed	Remove inconsistent mount entries from the /etc/exports file and restart the Phoenix Backup Store service. Revert the ZFS custom properties to the original and restart the Phoenix Backup Store service.
4295622667	Backup Mount	Backup mount marked for delete on Export Service.	Backup mount is getting deleted.	Either wait for the deletion or delete the backup mount from Phoenix Backup Store manually using the following command: zfs destroy /Phoenix/<deleted_mount_name> Restart PhoenixBackupStore service
4295622670	RMAN backing up data	Failed to export path to NFS.	Druva internal error.	Clean up the etc/exports file for non-existing NFS paths.
4295622659	RMAN writing backup data to backup mount	START_BACKUP cmd not received yet.	The PUT request to the API was made before the POST request.	Send the start backup command before triggering the backup scripts
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.	Either wait for the recovery points to be uploaded or deleted or update the following parameter in the /etc/Phoenix/ORACLE/Phoenix.cfg file to increase the number of pending recovery points on Phoenix Backup Store: MAX_ORACLE_recovery pointS = 5 The default limit is 5. Update it based on the space available on the Phoenix Backup Store. The pending recovery point might consume space on PBS. Restart the Phoenix Backup Store service using the following command: service PhoenixBackupStore restart
4295622663	Deleting Oracle RMAN backup downloaded from Druva Cloud	Restore Path is missing on Export Service.	The following are the possible causes: Restore path does not exist Restore path is not exposed to NFS	Make sure that you provide the correct restore path