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

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. 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_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 Phoenix 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 Phoenix map a database to its files in the Oracle RMAN backup. The mapping between a database and its file is useful when a Phoenix administrator runs a restore job. If this mapping is available, the Phoenix 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 Phoenix 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 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.

  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 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/testmount/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": "testmount",
        "jobid": 242135
     }
}

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

The example workflow demonstrates how the Phoenix Backup Store API works with RMAN to backup Oracle databases. Ensure that you update parameters and paths based on your setup. 

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