Skip to main content
Druva Documentation

Phoenix Backup Store REST API reference

Phoenix Editions: File:/tick.png Business File:/cross.png Enterprise File:/tick.png Elite

The availability of this feature is limited based on the license type, region, and other criteria. To access this feature, contact your Druva Account Manager or Druva Support. This article/documentation is subject to change based on the continuous improvements to this feature.

When an Oracle Database Administrator runs the template backup script that Druva provides, the following steps are performed to backup Oracle databases:

  • The status of the Phoenix Backup Store is checked
  • RMAN commands are run
  • An Oracle RMAN backup is created
  • The Oracle RMAN backup is stored on the backup mount of a Phoenix Backup Store.

Along with RMAN, the template script uses the REST API available on the Phoenix Backup Store to perform the Oracle database backup steps. To review the contents of the scripts, see:

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:

  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/test-mount/backup 2> /dev/null

    test-mount is the name of the backup mount used in this example.

  2. The Phoenix Backup Store returns a JSON object. For example:  
    {
        "error_code": 0,   
        "error_msg": “”,
        "result": {
            "mount_name": "test-mount", 
            "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/test-mount/backup 2> /dev/null
    
  4. The Phoenix Backup Store returns a JSON object. For example:  
    {
        "error_code": 0,   
        "error_msg": “”,
        "result": {
            "mount_path": "/Phoenix/test-mount/oracle_data",
            "mount_name": "test-mount", 
            "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. After the RMAN commands are run and the execution control returns to the script, the script makes a PUT request to notify the  Phoenix Backup Store that the Oracle RMAN backup was written successfully to the backup mount. For example:
    curl -X PUT http://192.0.2.1:9090/druva-phoenix/v1/mounts/test-mount/backup 2> /dev/null
    
  6. The Phoenix Backup Store returns a JSON object. For example:
    {
        "error_code": 0,
        "error_msg": "",
        "result": {
            "snap_name": "UID_1",
            "mount_name": "test-mount",
         }
    }
    

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

  7. 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 Phoenix Cloud. The snapshot serves as a restore point, and it is retained on the Phoenix Cloud based on the retention policy.

Note: The Phoenix Backup Store deletes the ZFS snapshot after it successfully uploads it to the Phoenix 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 Phoenix Cloud. 

When a snapshot is downloaded from the Phoenix 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/mnt/restores/test-mount/242135/data

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": "test-mount",
        "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. Phoenix 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 Phoenix Cloud

Restore Path is missing on Export Service.

Possible reasons:

  • Restore path does not exist
  • Restore path is not exposed to NFS