Veritas NetBackup™ DataStore SDK Programmer's Guide for XBSA 1.1.0

Last Published:
Product(s): NetBackup (8.2, 8.1.2)
  1. Introduction to NetBackup XBSA
    1.  
      About Introduction to NetBackup XBSA
    2.  
      What is NetBackup XBSA?
    3.  
      What does NetBackup XBSA do?
    4.  
      Terminology
    5.  
      Important concepts
    6.  
      Resources
  2. How to set up the SDK
    1.  
      System requirements
    2. Installing the SDK
      1.  
        Installation requirements
      2.  
        Installation instructions for UNIX platforms
      3.  
        Installation instructions for Windows platforms
    3.  
      Uninstalling the SDK
    4.  
      Configuration
    5.  
      Description of the XBSA SDK package
    6.  
      Library files
    7.  
      Header files
  3. Using the NetBackup XBSA interface
    1.  
      Getting help with the API
    2. NetBackup XBSA data structures
      1.  
        Object data
      2.  
        Object descriptors
      3.  
        Query descriptors
      4. Buffers
        1.  
          Buffer size
        2.  
          Private buffer space
        3.  
          Use of BSA_DataBlock32 in BSASendData()
        4.  
          Use of BSA_DataBlock32 in BSAGetData()
        5.  
          Shared memory
    3. NetBackup XBSA environment
      1.  
        Environment variable definitions
      2.  
        Extended environment variable definitions
    4. XBSA sessions and transactions
      1. Sessions
        1.  
          Initialization and termination
        2.  
          Authentication
      2. Transactions
        1.  
          Backup transaction
        2.  
          Restore transaction
        3.  
          Delete transaction
        4.  
          Query transaction
        5.  
          Media IDs transaction
    5. Creating a NetBackup XBSA application
      1. Initiating a session
        1.  
          Modifying the XBSA environment within a session
        2.  
          Session example
      2. Backup - creating an object
        1.  
          Creating an object
        2.  
          NetBackup object ownership
        3.  
          Creating an empty object
        4.  
          Backup example
      3. Query - finding an object descriptor
        1.  
          Querying for an object
        2.  
          Query example
      4. Restore - retrieving an object's data
        1.  
          Restoring an object
        2.  
          Redirected restore to a different client
        3.  
          Restore example
        4.  
          Multiple object restore
        5.  
          Multiple object restore example
      5. Delete - deleting an object or image
        1.  
          Delete example
      6. Media IDs - obtaining media IDs
        1.  
          Media ID example
      7.  
        Logging and NetBackup
      8.  
        Client in a cluster
      9.  
        Performance considerations
  4. How to build an XBSA application
    1.  
      Getting help
    2.  
      Flags and defines
    3.  
      How to build in debug mode
    4.  
      How to debug the application
    5.  
      Static libraries
    6.  
      Dynamic libraries
    7.  
      End-user configuration
  5. How to run a NetBackup XBSA application
    1. About How to run a NetBackup XBSA application
      1. Creating a NetBackup policy
        1.  
          Selecting a storage unit
        2.  
          Adding new schedules
        3.  
          Adding script files to the files list
        4.  
          Adding new clients
      2.  
        Running a NetBackup XBSA application
      3.  
        Backups and restores initiated by NetBackup (through a script)
      4.  
        Backups and restores from the command line
  6. API reference
    1.  
      Error messages
    2. Function calls
      1.  
        Conventions
    3. Function specifications
      1.  
        BSABeginTxn
      2.  
        BSACreateObject
      3.  
        BSADeleteObject
      4.  
        BSAEndData
      5.  
        BSAEndTxn
      6.  
        BSAGetData
      7.  
        BSAGetEnvironment
      8.  
        BSAGetLastError
      9.  
        BSAGetNextQueryObject
      10.  
        BSAGetObject
      11.  
        BSAInit
      12.  
        BSAQueryApiVersion
      13.  
        BSAQueryObject
      14.  
        BSAQueryServiceProvider
      15.  
        BSASendData
      16.  
        BSATerminate
      17.  
        NBBSAAddToMultiObjectRestoreList
      18.  
        NBBSADeleteImage
      19.  
        NBBSAEndGetMultipleObjects
      20.  
        NBBSAFreeJobInfo
      21.  
        NBBSAGetEnv
      22.  
        NBBSAGetErrorString
      23.  
        NBBSAGetJobId
      24.  
        NBBSAGetJobInfo
      25.  
        NBBSAGetMediaIds
      26.  
        NBBSAGetMultipleObjects
      27.  
        NBBSAGetServerError
      28.  
        NBBSALogMsg
      29.  
        NBBSASetEnv
      30.  
        NBBSAUpdateEnv
      31.  
        NBBSAValidateFeatureId
    4. Type definitions
      1. Enumerated types
        1.  
          BSA_CopyType
        2.  
          BSA_ObjectStatus
        3.  
          BSA_ObjectType
        4.  
          BSA_Vote
        5.  
          Constant values
      2. Data structures
        1.  
          BSA_ApiVersion
        2.  
          BSA_DataBlock32
        3.  
          BSA_ObjectDescriptor
        4.  
          BSA_ObjectName
        5.  
          BSA_ObjectOwner
        6.  
          BSA_QueryDescriptor
        7.  
          BSA_SecurityToken
  7. Process flow and troubleshooting
    1.  
      About Process flow and troubleshooting
    2. Backup
      1. Stream backup process flow description
        1.  
          Stream backup procedure
    3. Restore
      1. Stream restore process flow description
        1.  
          Stream restore procedure
  8. How to use the sample files
    1. What the sample files do
      1. Sample programs
        1.  
          Backup
        2.  
          Restore
        3.  
          Query
        4.  
          Delete
      2.  
        Sample scripts
    2.  
      Description of sample files
    3.  
      How to build the sample programs
  9. Support and updates
    1.  
      About Support and updates
  10. Appendix A. Register authorized locations
    1.  
      Registering authorized locations used by a NetBackup database script-based policy

Stream backup procedure

The stream backup procedure is as follows:

  1. nbpem determines that a backup is scheduled to run and it initiates a backup job by nbjm.
  2. nbjm starts bpbrm, which makes a request by bpcd.
  3. bpbrm makes a request by the bpcd daemon to start bphdb on the client.
  4. bphdb executes the backup script (which is contained in the Backup Selections list of the backup policy). Bphdb waits for an exit status from this script so that it can pass a status back to the server.
  5. The backup script initiates the backup utility of the XBSA application.

    (If it is not a scheduled backup operation, but is initiated on the client by the XBSA application, then the backup process starts here.)

  6. The application initiates the XBSA interface by starting one or more sessions. Each session should be started in its own process. In this diagram, we assume that there is only one stream. In reality, each stream follows each of these steps.
  7. The backup is initiated with the first call to BSACreateObject(). This causes the XBSA interface to make a bprd request to initiate a backup.
  8. bprd submits a backup request to nbpem, which submits a job for nbjm. If this was a scheduled backup, there are now two backup jobs. nbjm initiates a bpbrm and a bpdbm process.
  9. bpbrm initiates a bptm/bpdm process (bptm if tape storage unit, bpdm if disk storage unit). bptm initiates the process to mount media.
  10. bpbrm writes progress information to the progress file on the client (by bpcd). This information includes sockets, status, backup attributes, and so on.
  11. XBSA reads the progress file to find the sockets and other information and connects to bpbrm on the name socket. It continues to read the progress file until it gets the message that it can continue the backup.
  12. XBSA connects to bptm/bpdm through shared memory (if applicable) or on the data socket if the client and media server are separate machines.
  13. XBSA sends the XBSA object entry to bpbrm, which sends it on to bpdbm to be catalogued.
  14. At this point, BSACreateObject() returns to the XBSA application. XBSA is ready to receive data.
  15. The application fills buffers and calls BSASendData() to have the XBSA interface send these buffers to bptm/bpdm through the established connection.
  16. bptm/bpdm writes this data to media or disk storage.
  17. When the application has sent all of the data, it indicates this with a BSAEndData() call. XBSA recognizes that the object is complete.
  18. The XBSA application can then call BSACreateObject() again to create more objects. The subsequent CreateObject calls do not cause new jobs or connections, but continue with the existing processes.
  19. When the XBSA application has completed creating objects, a call to BSAEndTxn() causes XBSA to initiate the termination process. XBSA sends a client status to bpbrm, that terminates the server processes (bptm).
  20. bpbrm writes the server status to the progress log and is read by XBSA. This allows the XBSA interface to confirm that the image has been successfully catalogued and all of the data was written to media.
  21. XBSA then passes this status back to the application through the return status from BSAEndTxn(). This status is passed back to bphdb, that passes it back to the original scheduled job to complete the backup. This status displays in the Activity Monitor for the originally scheduled job.