BC-BRI BACKINT Interface for Oracle Databases

Transcription

1 BC-BRI BACKINT Interface for Oracle Databases Interface Specification: Oracle Database Administration February 2012

2 TABLE OF CONTENTS INTRODUCTION TO BR*TOOLS... 4 BR*Tools for Backup, Restore, and Recovery... 4 BRBACKUP... 5 BRARCHIVE... 6 BRRESTORE... 6 BRRECOVER... 7 BACKINT Interface to External Backup Tools... 8 Link to the Computing Center Management System... 8 I: BACKINT INTERFACE FOR ORACLE DATABASES Interface Functions Backup Function Restore Function Inquire Function Formal Definition of the Interface Program for the Backup Utility Basic Parameters Parameter <type> = file Parameter <type> = file_online Control Parameters Input File Contents Output File Contents Variable Definition Input/Output File Correlation BACKINT Return Code Examples Known Problems and Additional Information Online Backups with Function Type BACKINT Definition Configuration and Function of the External Backup Tool Support for Offline Backups with the Parameter file_online II: EXTENSIONS TO BACKINT INTERFACE Aims Concepts Prerequisites Formal Description of Extensions New Values volume and volume_online for BACKINT Option -t (type) New Values mount and dismount for BACKINT Option -f (function) New BACKINT Option n (negative) Extended Output of Information on the Backup Utility Volume User-Defined Additional Options for BACKINT Optional Progress Information Generated by BACKINT Optional Database Suspend and Resume for Disk Split URL for Additional Backup/Restore Information Additional Environment Variables for BACKINT New BR*Tools Parameters for Volume Backup in the init<dbsid>.sap Profile

3 backup_dev_type = util_vol util_vol_online util_vol_unit = disk_vol sap_data all_data all_dbf util_vol_access = none copy mount both util_vol_nlist = (<nfile_name1>, <nfile_name2>, ) no_check util_vol_options = < backint_volume_backup_options> util_options = < backint_options> util_vol_path = <backint_volume_backup_directory> util_path = <backint_directory> Copying of Snapshot or Clone Files to Tertiary Storage Examples of Backup, Restore/Recovery and Verify Procedures Complete Online Backup of the Database with Verification on Database Host with mount Access Complete Offline Backup of the Database with Verification on Database Host with copy Access Complete Recovery with BRRECOVER after the Loss of a Database File on Database Host Verification of a Disk-Volume Backup with BRRESTORE on Backup Host with mount Access Compatibility and Final Comments APPENDIX A: QUICK TEST ENVIRONMENT Installing the Oracle Database Creation of Database Objects Installation of BR*Tools Installation of BACKINT Users, Privileges, and Environment Installation Information Testing Information Complete Test Sequence APPENDIX B: BACKINT INTERFACE TEST References

4 INTRODUCTION TO BR*TOOLS The database server plays an important role in the server technology of SAP Business Solutions. In response to customers requesting support for administrative tasks, SAP has included several database administration tools in the standard SAP System package. These tools can be used, for example, for backup and recovery. For a long time, only basic backup programs (for example dd, cpio, tar) were available for open operating systems like UNIX. These are not suitable for backing up a relational database because they do not: Deal with special problems that might occur during database backup Provide tape management Therefore, SAP offers its own backup programs. These tools enable you to easily and completely back up the SAP system, so that your system runs smoothly. There is also a BACKINT interface that integrates the most common client/server backup programs. SAP provides the following BR*Tools for Oracle database administration: BRBACKUP, BRARCHIVE, BRRESTORE, and BRRECOVER Database backup, restore and recovery BRCONNECT BRSPACE (database statistics, database check, cleanup logs and traces) Database administration (for example, database startup or shutdown, tablespace extension, space management, reorganization. You can access the entire functionality of BR*Tools using a graphical user interface (BRGUI) or a character interface (BRTOOLS). For more information, see References [page 37]. The following platforms are supported: HP-UX, AIX, Solaris, Windows, Linux We have recently introduced an optional extension to the Backint interface, available in BR*Tools For more information, see II: EXTENSIONS TO BACKINT INTERFACE [page 21]. There is only one small extension affecting the standard BACKINT specification. This concerns the $SAPSWITCH/%SAPSWITCH environment variable in specifying the location of the.switch files. For more information, see Parameter <type> = file_online [page 13]. BR*Tools for Backup, Restore, and Recovery BRBACKUP and BRARCHIVE are command-line programs for data backup, which you can also schedule in the background. Online help provides information on available options. Both programs issue messages in English or German. Backups are based on the following programs: cpio, dd in a UNIX environment (for a backup to disk: cp, dd) MKS 1 -cpio, MKS-dd for Windows (for a backup to disk: copy, MKS-dd already deprecated) 1 MKS and MKS Toolkit are trademarks of Mortice Kern Systems Inc. 4

5 External backup programs accessed using the BACKINT interface program see figure Backup of the Oracle Database Using an External Backup Tool [page 8] Oracle Recovery Manager (RMAN) Oracle Backup (Native) Using cpio or dd Control files Data files Oracle Database Online redo log files Offline redo log files BRBACKUP BRRECOVER BRRESTORE BRARCHIVE Detail and summary log cpio/dd parallel cpio/dd serial Detail and summary log Backup Media Backup Media BRBACKUP and BRARCHIVE log all actions in the file system and database tables, and also save backup logs and profiles to backup media. BRBACKUP and BRARCHIVE enable comprehensive volume management. To use the functions provided, you must initialize the volumes with BRBACKUP or BRARCHIVE to ensure that they include an SAP-specific label. You cannot overwrite volumes that have not been released for use if the label specifies that they are still locked. You can determine the names and number of volumes required for BRBACKUP or BRARCHIVE in advance using the query mode, without starting a backup. The programs let you verify completed backups in detail. You can use BRRESTORE and BRRECOVER to restore and recover an Oracle database that was backed up using BRBACKUP and BRARCHIVE. BRBACKUP BRBACKUP enables an online or offline backup of the control file, of data files in some or all tablespaces and, if necessary, of the online redo log files. See figure Oracle Backup (Native) Using cpio or dd [page 5]. BRBACKUP also saves the profiles and logs relevant to the backup. In addition to the actual backup, BRBACKUP also: Automatically changes the state of the database (opened or closed), depending on the type of backup (online or offline) 5

6 Checks the status of files Sets the tablespace backup status (BEGIN / END BACKUP) Optimizes data distribution on the backup media. The algorithm for distribution is specially adapted to the requirements of a database backup (backing up a small number of large files). Data distribution depends on whether you perform a serial or parallel backup. Uses software compression, if this option is set. Saves to hardware compressing tape devices, taking into account previously determined compression rates. During a backup, BRBACKUP starts another tool, BRCONNECT, which makes sure that the database status required for the online or offline backup remains unchanged during the backup. You can also back up specific files or directories. However, a backup of a directory only includes the files located in the root of the directory without any subdirectories. This enables you to back up all SAP objects that are not part of the database (for example, programs, SAP start profiles, selected logs, and so on). For more information, see References [page 37]. BRBACKUP is not designed to back up complete file systems (that is, systems with many small files and directories). BRARCHIVE BRARCHIVE lets you back up the offline redo log files. These are the online redo log files saved to the archiving directory by Oracle. See figure Oracle Backup (Native) Using cpio or dd [page 5]. BRARCHIVE also saves all logs and profiles relevant to the backup. It supports tapes and disks as storage media. We recommend backing up offline redo log files because: In the event of failure, a consistent database status can only be recovered if all the relevant redo log files are available. The database system of a productive SAP System has to run in ARCHIVELOG mode (to prevent overwriting online redo log files not yet saved). To protect the archive directory against overflowing, it must be emptied regularly. An online backup of data files is of no use if the related redo log files are missing. Therefore, it is necessary to back up the offline redo log files generated during the online backup immediately after running BRBACKUP. For security reasons, BRARCHIVE in native mode (with cpio or dd) offers duplicate archiving of offline redo log files redundant serial or parallel archiving is possible. Serial duplication is also available for BACKINT. Using the logs, BRARCHIVE can ensure that redo log files are not deleted before they have been backed up and that these files are saved either once or twice. BRARCHIVE lets you continuously back up offline redo log files. This means that the backup directory, where Oracle stores the offline redo log files, can be kept clear by continuously backing up and then deleting current redo log files. BRRESTORE BRRESTORE lets you restore files of the following type: Database data files, control files, and online redo log files saved using BRBACKUP Offline redo log files backed up using BRARCHIVE Non-database files saved used BRBACKUP Profiles and logs (normally only necessary in the event of a disaster) 6

7 You can specify files, tablespaces, complete backups, log sequence numbers of redo log files, or the position of a file on tape. BRRESTORE automatically determines the corresponding backup tape and the position of the files on the tape. BRRESTORE checks whether the required free disk space is available to allow the files to be restored and then restores the directory and link structure automatically. Directory $SAPDATA_HOME and mount points sapdata<n> must exist. BRRECOVER BRRECOVER offers menu options for restore or recovery specially designed to reflect user needs. BRRECOVER can: Recover the database to the current state after media error in several files, for example, due to a disk failure Restore the entire database for a point in time recovery or reset the database to a previous state BRRECOVER evaluates the backup logs to decide whether the specified recovery can be performed using the selected backups. For example, for a point-in-time recovery, BRRECOVER determines whether any actions that would prevent the recovery have taken place between the time of the backup and the selected recovery end time. If BRRECOVER cannot perform a recovery, it rejects the selected backup or the specified recovery procedure. Data can only be recovered automatically using BRRECOVER if BRBACKUP and BRARCHIVE (in native mode or with the BACKINT interface) were used for the backup. In this respect, the SAP tools BRBACKUP, BRARCHIVE, BRRESTORE, and BRRECOVER function as an integrated solution: Integrated Solution for Backup, Restore, and Recovery Control files Oracle Database Data files Online redo log files Offline redo log files Restore and Recovery BRRECOVER BRBACKUP BRRESTORE BRARCHIVE Detail and summary log Detail and summary log Detail and summary log Control files Data files Online redo log files Offline redo log files Backup Media 7

8 BACKINT Interface to External Backup Tools SAP BR*Tools can call the BACKINT interface program so as to communicate with an external backup program: Backup of the Oracle Database Using an External Backup Tool Database files Offline redo log files Oracle database SAP tool BRBACKUP BRARCHIVE BRRESTORE BRRECOVER Interface program BACKINT BACKINT BACKINT BACKINT External backup / restore program External BACKUP server Media BR*Tools are responsible for all database-related tasks. For backup and restore, they send requests to the BACKINT interface. BRRECOVER can request restore of profile and log files in the event of disaster recovery. BACKINT is generally implemented and sold by the vendor of the external Media Management Software (MMS). SAP is responsible for defining BACKINT and guarantees the functionality of BR*Tools. We recommend using BACKINT to implement a company-wide, uniform backup strategy. A major advantage is that it allows easy database administration using BR*Tools, particularly for database recovery. Link to the Computing Center Management System The Computing Center Management System (CCMS) see References [page 37] supports the use of BR*Tools with the following functions: Scheduling of an online backup with BRBACKUP Starting an offline backup with BRBACKUP Starting offline redo log backup with BRARCHIVE The same functions are available when using BRBACKUP and BRARCHIVE with the BACKINT interface. The DBA Cockpit in CCMS lets you display the following: 8

9 An overview of all backups performed using BRBACKUP or BRARCHIVE see figure Backup Overview in DBA Cockpit [Page 9] below. All details see figure Backup Details in DBA Cockpit [page 10] below, including the action runtimes and the amount of data processed Backup Overview in DBA Cockpit 9

10 Backup Details in DBA Cockpit 10

11 I: BACKINT INTERFACE FOR ORACLE DATABASES The link from SAP BR*Tools to the external backup and restore program is based on the interface program BACKINT: see figure Backup of the Oracle Database Using an External Backup Tool [page 8] above. BACKINT processes the requests for backup, restore, and inquire, and executes them using the corresponding backup tool. If the Media Management Software (MMS) is a client/server program, BACKINT communicates with the server program running on the backup server. Interface Functions The BACKINT interface supports the following functions (see figure Backup of the Oracle Database Using an External Backup Tool [page 8] above): Backup Restore Inquire In all cases, the mandatory user ID (UID) option is used as an identifier for the SAP database. After a function has been executed, the interface program always returns an integer return code indicating whether the call was successful. The user ID plays a significant role during a database copy. In this case BRRESTORE can request a restore of a backup with a given user ID on another server. Backup Function This defines a backup request including all files specified in a list. If the backup request cannot be processed completely, the interface program informs the user which files have been backed up successfully (partial backup). MMS determines the sequence in which the files are saved. On return, MMS generates a backup ID (BID) for each saved file, clearly identifying the backup. A backup file is uniquely identified by: User ID Backup ID File name Restore Function This is used to pass a restore request to MMS, consisting of a user ID (UID), backup ID (BID), a list of files to be restored, and a list of directories where files should be created. The last parameter is optional. If it is not set, the file is restored to its original location. If the backup ID is not set, the last backup of the related file is used. The return information indicates which files were restored successfully and which backup IDs were used. Inquire Function This provides information about the backups managed by the Media Management Software (MMS). This function is called using the UID, BID, and the file name (the last two parameters are optional). If both optional parameters are specified, the system checks whether this file was saved with a specific BID. If the BID is not set, a list of available backup IDs (BIDs) is provided, including the specified file. If a file name is not specified, a list of files belonging to a specific BID is generated. If neither of the two parameters is set, a list of available backups with BIDs is generated. In general, the BID does not always identify a backup run, although this is normally true. It can also identify the backup of a single file or a group of files. The BACKINT interface does not distinguish between Oracle single instance and Real Application Cluster (RAC) installations. Based on this distinction, BR*Tools alone executes the required database handling. 11

12 Formal Definition of the Interface Program for the Backup Utility BACKINT uses a call interface at command line level with the following syntax: backint -u <user_id> [-f <function>] [-t <type>] [-p <par_file>] [-i <in_file>] [-o <out_file>] [-c] You can find descriptions of the parameters user_id, function, type, par_file, in_file, out_file in the sections Basic Parameters [page 12] and Control Parameters [page 15]. In addition to the command line options, the interface also supports some environment variables set by BR*Tools before BACKINT is called: Environment Variable Value Description BI_CALLER BI_BACKUP BI_REQUEST BRBACKUP BRARCHIVE BRRESTORE BRRECOVER FULL PARTIAL ARCHIVE NEW OLD BACKINT is called by BRBACKUP, BRARCHIVE, BRRESTORE, or BRRECOVER Full database backup, partial database backup, or offline redo log backup First call or following BACKINT calls within a run of BRBACKUP, BRARCHIVE, BRRESTORE, or BRRECOVER. BACKINT can be called multiple times during one run of an SAP tool. BR*Tools sets the environment dynamically (using putenv), and BACKINT, as the child process, inherits these variables (using getenv) and can use them to control further processing. For example, we recommend that you do not change the order of the offline redo log files (BI_BACKUP = ARCHIVE) during the backup. The best practice is to back up the offline redo log files in the order specified in the input file (see option i). This lets BRARCHIVE empty the archive directory as quickly as possible. Basic Parameters Option Parameter Description Default -u <user_id> <user_id> (UID) Backup tool user, normally database instance name (ORACLE_SID) -f <function> <function>: backup restore inquire Type of operation see figure Backup of the Oracle Database Using an External Backup Tool [page 8] above -t <type> <type>: file file_online Backup type: backup of individual files, directories, character special devices None backup file 12

13 -c Unattended mode (no interaction with operator possible) Attended mode Parameter <type> = file Backup type file for functions backup, restore, inquire (see table above) is the default for handling data files and directories as well as character special devices (that is, raw disks). Oracle assumes one file per raw disk. Such a disk cannot be shared among different files. Therefore, BACKINT is used in the same way as for regular files, except that all the file names in the input file are character special device files, each followed by the file size used by Oracle. The minimum backup should include at least this amount of data starting from the beginning of the partition. The file size is only specified if BACKINT is called for the backup function. On some platforms Oracle files do not start on raw partitions from byte 0, but rather with a certain offset (for example, 4 KB for AIX). This offset, used for control data of the logical volume manager, must be taken into account when backing up files from raw partitions. The offset must be skipped or added to the file size set in the input file. In addition, while restoring database files to raw partitions, the control information at the beginning of the partition must not be overwritten it must be skipped. When directories are saved, only objects at the root of the directory are saved, not the contents of the subdirectories. If the directory object is a subdirectory, only the definition is saved, not the contents of the subdirectory. BRBACKUP expands the directory structure itself if necessary. An error should be reported if such a directory backup is not supported by the Media Management Software (MMS). BACKINT has to check if the name stands for a file, directory or raw partition. Since profiles and logs remain in a file system and are backed up, the list of objects can be mixed. Parameter <type> = file_online The backup type file_online allows BRBACKUP to switch the tablespace into BEGIN / END BACKUP mode only when backup of the related files actually occurs. Backup type file_online uses the following files: File UNIX: File in $SAPSWITCH if set, otherwise in $ORACLE_HOME/sapbackup Windows: File in %SAPSWITCH% if set, or %SAPBACKUP% if set, otherwise in %SAPDATA_HOME%\sapbackup Switch-list.switch.lis.switch.lis Switch-semaphore.switch.sem.switch.sem Switch-log.switch.log.switch.log Note the location of the.switch.* files defined in the column headings of the above table. Communications are described by specifying the tasks for BACKINT and BRBACKUP. BACKINT creates a switch-list file whenever it wants to back up a file (#BACKUP) or whenever it wants to indicate that a backup is finished (#END): #BEGIN #END <file1> [#BEGIN #END <file2>] 13

14 BACKINT must not send multiple #BEGIN / #END messages to BRBACKUP (actually, to BRCONNECT) for the same file. If you need to restart a file backup during a backup session, you must do this within a single #BEGIN #END interval. You can put multiple lines into a single switch-list file, mixing #BEGIN and #END lines. Therefore, it is a good idea to put as many files into a single switch-list file as possible. Normally, it is best to put the first files of all parallel BACKINT backup processes in the first switch-list file. During the backup, when BACKINT is about to back up the next file, put both files, the previous one and the next one, into the switch-list file: #END <previous_file> #BEGIN <next_file> This lets BRBACKUP (actually, BRCONNECT) minimize the number of tablespace BEGIN/END BACKUP switches. After the switch-list file has been created and closed, BACKINT creates the empty switch-semaphore file and waits the wake-up period is determined by BACKINT, approximately 1 to 4 seconds until this file has been deleted by BRBACKUP (actually, BRCONNECT). It can take several minutes to put a tablespace into the backup state. Therefore, BACKINT should wait at least 20 minutes before reporting timeout and aborting processing. After the switch-semaphore file has been deleted, BACKINT opens and reads the switch-log file. The operation is successful and BACKINT continues processing if it finds a single line in this file that includes: #SUCCESS However, the operation has failed and BACKINT terminates with an error if it finds a single line that includes: #ERROR All lines except those with the keywords #SUCCESS or #ERROR are copied to the output file (see -o option). BACKINT deletes the switch-log file after reading it. Messages written to the output file should be flushed after each line. BRBACKUP (actually, BRCONNECT) periodically checks if such a switch-semaphore file exists and sets the wake-up period. If BRBACKUP (actually, BRCONNECT) detects a switch-semaphore file, it opens and reads the switch-list file, then issues and logs the appropriate begin/end backup statements in the switch.log file. After completion, it deletes the switch-semaphore file and the switch-list file. BACKINT is then allowed to proceed. BRBACKUP (actually, BRCONNECT) decides when to put a tablespace into BEGIN/END BACKUP mode by using a history of former requests. This is necessary because only BRBACKUP (actually, BRCONNECT) knows when any of the data files of one specific tablespace are backed up. During a backup run, only one process can communicate with BRBACKUP (actually, BRCONNECT) in order to perform the tablespace status switch. If you are using multiple parallel 14

15 processes or sessions to back up the files, you must coordinate this through a master process (normally the BACKINT process) to avoid unpredictable results. All handles to the switch files should be released (that is, closed) before giving up the handshake control to BRBACKUP (actually, BRCONNECT). This lets BRBACKUP (actually, BRCONNECT) delete these files without problems. Control Parameters Option Parameter Description Default Type -p <par_file> <file> -i <in_file> <file> -o <out_file> <file> Input File Contents Parameter file for backup utility containing parameters that determine the backup procedure specific to the backup utility. The SAP tools specify the location of this utility parameter file in their own parameter file (parameter util_par_file util_vol_par_file), but they do not evaluate its contents. Text file that defines the objects of the function (backup, restore, or inquire). If this parameter is not set, data is read from the standard input. Output file for processing messages and the results of the executed function. If this parameter is not set, the messages are written to the standard output. The contents of the input file <in_file> depend on the backup function: none STDIN STDOUT See table Input File Format [page 15]. See table Output Message Format [page 16]. Input File Format Function Input Entries backup Names of files and directories to be saved. Character special file restore Names of files to be restored using BIDs: #NULL: last backup optional: use changed target directories or raw disks inquire Names of files and/or BIDs about which information is requested. #NULL: no backup ID See also table Correlation of Input and Output Values for the Inquire Function <file1> [<file2>] <special_file1> <size1> [<special_file2> <size2>] <backup_id> <file1> [<dest_dir1>] [#NULL <file2> [<dest_dir2>]] #NULL [<backup_id>] [#NULL <file1>] [<backup_id> <file2>] 15

16 [page 17]. <backup_id> Backup ID assigned by the MMS, passed on as a return value in connection with the backup function; can only be set in the input file using the restore and inquire functions. For comments on the size of the raw partition to be backed up, see Caution on page 13. When restoring the raw partition to a different one than the original, the <dest_dir> means the new raw partition, not the directory containing the special file. Output File Contents In addition to the messages with fixed format defined below, the file might contain other messages that are simply passed on to the user. If the output file is not specified, the output is sent to the standard output (STDOUT). The contents of the <out_file> output file depend on the backup function: Output Message Format Function Successful Messages Error Messages backup #SAVED <backup_id> <file> [<backup_vol>] #ERROR <file> restore #RESTORED <backup_id> <file> #NOTFOUND <file> #ERROR <file> inquire #BACKUP <backup_id> #BACKUP <backup_id> <file> See also table Correlation of Input and Output Values for the Inquire Function [page 17]. #NOTFOUND <file> #ERROR <file> Note the following for messages written to the output file: Messages should be flushed after each line Messages must not be longer than 1024 characters. BACKINT should avoid writing any other lines starting with the character # to the output file. This can disturb the work of BRRECOVER tool, which is sensitive to such lines generated by BRBACKUP and BRARCHIVE. If needed, write such lines only to your own logs. Variable Definition All entries have a variable character format as described in the following table: Type of Entries Entry Description Type (maximum length) <file> File, directory char(255) <special_file> Raw device char(255) <dest_dir> Directory char(255) <size> File size in bytes char(16) <backup_id> Backup ID char(16) 16

17 <user_id> User ID char(16) <backup_vol> Backup volume (for example, tape label) optional char(10) <backup_id> can be any character string up to a length of 16 not containing any white spaces. Input/Output File Correlation The contents of the output file for the inquire function depend greatly on the type of request. We can distinguish the following cases: Correlation of Input and Output Values for the Inquire Function Case Input Output A BID and file name not specified (#NULL) List of BIDs for UID sorted by creation date (most recent backup first). One list line consists of one BID. B C BID specified, file name not specified BID not specified (#NULL), file name specified List of BIDs and related files in the specified backup. One list line consists of the specified BID and one file name. List of BIDs related to the specified file, sorted by creation date (most recent backup first). One list line consists of one BID and the specified file name. D BID and file name specified BID and file name, if available, in the specified backup. One list line consists of one BID and one file name. It should be only one line in the list. BACKINT Return Code BACKINT is called from BRBACKUP, BRARCHIVE, BRRESTORE, or BRRECOVER. All these programs expect BACKINT to return a code as described in the following table: BACKINT Return Code Return Code Description 0 OK All files were successfully processed without warnings 1 WARNING But all files were successfully processed > 1 ERROR - Some or all files were not successfully processed Examples Below you can find examples for using BACKINT to back up and restore a SAP/Oracle database instance identified by SID = C11, assuming a file named dummy contains the file name: /oracle/c11/sapdata1/user1i_1/user1i.data1 Backup Call BACKINT as follows for a backup: OS> backint -u C11 -f backup -t file -p 17

18 /oracle/c11/dbs/initc11.utl -i dummy -o dummy.out The output file dummy.out might look as follows: ********************* dummy.out *************************************** Program: backint Parameters: Client node: RC1 Function: backup Input File: dummy Output File: dummy.out Profile: /oracle/c11/dbs/initc11.utl Parallel sessions: 1 BKI0008I: Number of bytes to save: MB. Backup started... #SAVED SAP /oracle/c11/sapdata1/user1i_1/user1i.data1 BKI0022I: Bytes saved so far: MB (100.0%). *********************************************************************** Only the line starting with the keyword #SAVED is interpreted by SAP programs as described in Formal Definition of the Interface Program for the Backup Utility [page 12]. The rest is normally copied to the log file of the SAP program. Restore Restore the backup by setting the tag #NULL in front of the file name in dummy: #NULL /oracle/c11/sapdata1/user1i_1/user1i.data1 Call BACKINT as follows for a restore: OS> backint -u C11 -f restore -t file -p /oracle/c11/dbs/initc11.utl -i dummy -o dummy.out The output file dummy.out might look as follows: ********************* dummy.out *************************************** Program: backint Parameters: Client node: RC1 Function: backup Input File: dummy Output File: dummy.out Profile: /oracle/c11/dbs/initc11.utl Parallel sessions: 1 BKI0032I: Number of bytes to restore: MB. Restore process started... #RESTORED SAP /oracle/c11/sapdata1/user1i_1/user1i.data1 BKI0023I: Bytes restored so far: MB (100.0%). *********************************************************************** Only the line starting with the keyword #RESTORED is interpreted by SAP programs as described in Formal Definition of the Interface Program for the Backup Utility [page 12]. The rest is normally copied to the log file of the SAP program. Inquire 18

19 Perform the inquire by setting the tag #NULL in front of the file name in dummy (list of all backups in which this file was saved): #NULL /oracle/c11/sapdata1/user1i_1/user1i.data1 Call BACKINT as follows for an inquire: OS> backint -u C11 -f inquire -t file -p /oracle/c11/dbs/initc11.utl -i dummy -o dummy.out The output file dummy.out might look as follows: ********************* dummy.out ************************************** Program: backint Parameters: Client node: RC1 Function: backup Input File: dummy Output File: dummy.out Profile: /oracle/c11/dbs/initc11.utl Parallel sessions: 1 #BACKUP SAP /oracle/c11/sapdata1/user1i_1/user1i.data1 #BACKUP SAP /oracle/c11/sapdata1/user1i_1/user1i.data1 *********************************************************************** Only the line starting with the keyword #BACKUP is interpreted by SAP programs as described in Formal Definition of the Interface Program for the Backup Utility [page 12]. The rest is normally copied to the log file of the SAP program. In this example, two backups with different backup IDs were found. Generally, the backup ID includes a unique key that can consist, for example, of a class of objects and the time of the backup. This enables unique backup identification. Known Problems and Additional Information Online Backups with Function Type In general, a problem can occur if you run a complete online database backup using BRBACKUP BACKINT BACKUP utility and perform large-scale data manipulation language (DML) operations at the same time. Since BRBACKUP needs to set all the tablespaces in BACKUP status at the beginning of the backup, a large number of redo logs is created. If you do not consider this, it might lead to an archiver stuck. One consequence is that BRBACKUP cannot complete the operation (that is, update of its database catalog, end BACKUP status). To avoid this situation we recommend running BRARCHIVE with the -f option. If the problem is acute, use function type file_online. BACKINT Definition The file names transferred with the interface are always case sensitive, independent of the operating system. This means that they have to be returned (in #SAVED, #RESTORED, #NOTFOUND, #ERROR, #BEGIN, and #END) in the same form they were when they were transferred to the input file. Pay special attention to this requirement when running on Windows because file names are normally not case-sensitive on this platform. We recommend that BACKINT only uses the value of -u option <user_id> (not in combination with host name), to identify the calling client. SAP customers often use full database backup to create a system 19

20 copy on another host. This requirement to enable a restore on a host that differs from the backup host can also be indicated in another way, for example, by a special parameter in the parameter file. Configuration and Function of the External Backup Tool Experience has shown that some additional functions of the backup tool not subject to certification can be useful, particularly with respect to data security. We recommend that tool manufacturers offer the following functions: Backup verification You can use this to make sure that all backup tapes are readable in the event of a recovery. Ability to create two copies of the offline redo log files The backup tool should write the copies to separate tapes. The message (#SAVED), indicating that both files have been backed up successfully, should be output only once after both copies have been made. This procedure allows you to create two copies of the offline redo log files with one BRARCHIVE call, for example, brarchive sd, BACKINT call using the environment variables BI_CALLER= BRARCHIVE. It also improves security for a database recovery. An acceptable INQUIRE query time. This often takes too long, up to several minutes. The result is to lengthen the recovery process and the system downtime, which is particularly critical when many offline redo log files have to be restored. Tape label checking The backup tool should prevent unintentional overwriting of the tapes using a tape label and suitable locks. Support for Offline Backups with the Parameter file_online Starting with BR*Tools Release 6.10, the backup type file_online is also supported for offline backups. In this scenario, the database is stopped and started not before and after the BACKINT call, but during the BACKINT run. The database is: Stopped by the first #BEGIN message in the.switch.lis file Started again by the last #END message in the file This procedure enables split-mirror and snapshot scenarios for offline backups to be fully implemented in BACKINT. The following shows a typical sequence: 1. BRBACKUP is started with the following parameters: backup_type = offline and backup_dev_type = util_file_online 2. BRBACKUP starts BACKINT with the option -t file_online, without first stopping the database. 3. BACKINT passes the.switch.lis file to BRBACKUP (actually, to BRCONNECT), containing the #BEGIN message for all files to be backed up. 4. BRBACKUP (actually, BRCONNECT) then stops the database and deletes the.switch.sem file. 5. BACKINT splits the disk and passes the.switch.lis file to BRBACKUP (actually, to BRCONNECT) with the #END message for all files that are to be backed up. 6. BRBACKUP (actually, BRCONNECT) then starts the database and deletes the.switch.sem file. 7. BACKINT backs up the split files and passes the #SAVED messages to BRBACKUP. This extension to BRBACKUP functionality does not change the BACKINT specification. 20

21 II: EXTENSIONS TO BACKINT INTERFACE Aims The extensions to the BACKINT interface have the following aims: Better support of snapshot and cloning technology, which is increasingly becoming the industry standard Better methods to fully implement split-mirror disk technologies in BACKINT as an alternative to the support of the SPLITINT interface Enable use of BRRECOVER procedures for backup based on snapshot and cloning technologies The extensions support backups at the level of disk volume (volume backups), in addition to the backups at file level (file backups) available previously. Concepts Support of these extensions is optional. SAP Partners should clearly state in their BACKINT documentation whether and to what extent they support these extensions. By disk volume we normally mean a logical volume (file system / mount point / drive). This is the smallest unit that can be backed up with a snapshot or clone. Depending on the hardware and implementation, the smallest volume unit might also be bigger for example, a logical volume group. The BR*Tools Parameter util_vol_unit defines which volume unit is used in a specific configuration (for more information, see util_vol_unit = disk_vol sap_data all_data all_dbf [page 27] below). In the event of a restore, the database files are normally reset to the state of a selected snapshot or clone, which is known as snap-back or clone-back. However, it s often necessary to access such backups without overwriting the original files for example, for verification purposes or to copy back into other directories. This type of additional access is controlled by the BR*Tools parameter util_vol_access. For more information, see util_vol_access = none copy mount both [page 28]. This access normally uses a separate mount. But, depending on the implementation, the copying of individual files might be possible. To make the handling of disk volume backups easier, SAP recommends only complete backups. However, partial backups are still permitted. For partial backups BRBACKUP extends the list of database files to be backed up so that it always includes all database files on the selected volume units. See also New Values volume and volume_online for BACKINT Option -t (type) [page22]. Prerequisites To create backups at disk-volume level, you need to meet the following prerequisites: All database files are in sub-directories of sapdata directories or in sapraw for raw disks. All online redo log files are in origlog or mirrlog directories, or in sapraw for raw disks. All control files are in sapdata, origlog, or mirrlog directories, or in sapraw for raw disks. Normally sapdata, origlog, or mirrlog are mount points (UNIX) or are on separate drives (Windows). There are no other non-database files in these directories. If database files from these directories are backed up at disk-volume level, no other files from other directories can be backed up in the same BACKINT call. It must be possible to back up files from other directories (for example, saparch, sapbackup, sapreorg) with a separate BACKINT call at file level in the same backup run. The use of the new functionality is only allowed with the corresponding certified backup tools. 21

22 Formal Description of Extensions New Values volume and volume_online for BACKINT Option -t (type) The backup function -f backup expects to back up all files of the disk volumes that are being backed up. The disk volumes to be backed up are defined in the file list of the input file. All disk volumes are backed up for which at least one file is in this list. The input file still contains a list of file names, not a list of volume names. BACKINT checks that the file list in the input file is complete. This list must contain all files located on the volume units that need to be backed up. If there are files on the volume units that are not in the list, these files are reported with the following error message in the output file: #ERRFILE <file name> Then BACKINT terminates immediately with an error exit code, without having performed a backup. Note the following about #ERRFILE errors: The fixed files, specified by the file system or by snapshot/clone software (for example, lost+found,.snapshot, and so on) are not reported in #ERRFILE. In the new option n <nlist_file> there is an option to pass a text file to BACKINT. The text file contains a negative list of non-database files. For more information, see New BACKINT Option n (negative) [page 23]. Also for these files, there is no #ERRFILE message, although they can be located on the backup volumes and are not specified in the input file. If several hundred or thousand such files are found, only the first hundred should be reported. This check is also made for the restore function, not for mount, dismount, and inquire functions. Particularly with the restore function only some of the files on the volume units might be requested for restore. Other files on the backed-up volume, which were in the backup request (that is, they were in the file list of the input file) and which are not on the negative list, are reported in the #RESTORED messages when the entire volume is reset with snap-back or clone-back. The recovery procedure (BRRECOVER) is prepared for all files on the volume units to be overwritten. Files on the volumes to be overwritten, which are not in the restore request and were not in the backup request, and which are not on the negative list, are reported in the #ERRFILE messages. In this case, BACKINT terminates immediately with an error exit code, without having performed a restore. The completeness check of the input list is deactivated if the option n no_check is set. For more information, see New BACKINT Option n (negative) [page 23]. The logic of t volume_online has not changed. It remains like the logic of t file_online. However, note that, when backing up a disk volume, all files from the input list on this volume should be written to a single.switch.list file. The function f restore to restore a disk volume expects that all files from the input list are reset by snapback or clone-back. The disk volumes to be reset are defined like the backups. It is possible that other files on these disk volumes, which are not in the input list, are also reset. This happens when the original disk volumes are replaced by a snapshot or clone. However, if they need to be copied back to other locations that is, when <dest_dir> is set in the input file then individual files need to be copied from a volume backup, without overwriting other files. This is also true when <dest_dir> points to the original subdirectory. Since this functionality is optional, the backup utility does not have to support it. BR*Tools parameter util_vol_access specifies whether this functionality is available: Available: util_vol_access = copy both 22

23 Not available: util_vol_access = none mount For more information, see util_vol_access = none copy mount both [page 28], and example Complete Offline Backup of the Database with Verification on Database Host with copy Access [page 30]. Comments: Theoretically, even with the current values of the t option (file and file_online) the backup utility can internally use the volume logic (snapshots, clones). However, in must be able in the event of a restore to retrieve individual files from the backup without overwriting other files. Also in the opposite case (-t volume and t volume_online) the backup utility can internally back up and restore single files instead of disk volumes. However, this is not especially worthwhile because it actually excludes the use of snapshot or cloning technologies and has no advantages. New Values mount and dismount for BACKINT Option -f (function) These new functions are particularly for the verification of the disk volume backups based on the snapshot or cloning technologies. On request from BRBACKUP the backup utility allows access to the backed-up files, using paths determined by the backup utility (mount). Depending on the implementation, these mounts might not be possible on the productive computer but instead on another computer, such as a backup server. During verification, BRBACKUP only accesses the backed-up files using the mounts in read-only mode. The input file for the mount function has the following format: <backup_id1> <file1> <backup_id2> <file2>... The backup utility writes to the output file the sub-directories (or raw-disk paths) containing the backed-up files after the mount: #MOUNTED <backup_id1> <file1> <sub_dir1> #MOUNTED <backup_id2> <file2> <sub_dir2>... Obviously, the messages #NOTFOUND <file> or #ERROR <file> can be issued. The dismount function enables the backup utility to release the resources from the mount. The format of the input file is as follows: <backup_id1> <file1> <sub_dir1> <backup_id2> <file2> <sub_dir2> The format of the output file is: #DISMOUNTED <backup_id1> <file1> <sub_dir1> #DISMOUNTED <backup_id2> <file2> <sub_dir2>... Here too, the messages #NOTFOUND <file> or #ERROR <file> can be issued. New BACKINT Option n (negative) With the new option n, BACKINT can receive a negative list of files that are on the backup volumes but are not processed and do not appear in reports. This optional option has the following syntax: -n <nlist_file> no_check 23

24 where <nlist_file> is a text file containing a list of non-database files or directories in the following format (one file name per line): <nfile_name1> <nfile_name2> The files in the list are normally non-database files that are located on the database disk volumes, but are not explicitly specified in the input file, and are therefore not part of the backup/restore action. They can be implicitly processed but are never reported in the BACKINT interface messages #SAVED, #RESTORED, #BACKUP, #MOUNTED, #DISMOUNTED, #NOTFOUND, #ERROR, and #ERRFILE. Especially during a restore, they might be overwritten without prior warning. If a directory name is given, this is valid recursively for all files and sub-directories in the given directory. For each entry in the negative list, the overlying directories are implicitly part of the negative list, but not their content. Unlike directories mentioned in the negative list, these directories are not recursively processed. If $SAPDATA_HOME/sapdata1/a/b/c is in the negative list, this means that: o o $SAPDATA_HOME/sapdata1/a/b and $SAPDATA_HOME/sapdata1/a are also implicitly in the negative list. $SAPDATA_HOME/sapdata1/a/b/d or $SAPDATA_HOME/sapdata1/a/e are not in the negative list. It does not matter whether $SAPDATA_HOME/sapdata1/a/b/c is a file, a directory, or does not even exist. The value no_check deactivates the completeness check of the files in the input list. See New Values volume and volume_online for BACKINT Option -t (type) [page 22]. If this is set, all files located on the backup volumes but not in the input list can be implicitly processed. In this case no message is issued such as #SAVED, #RESTORED, #BACKUP, #MOUNTED, #DISMOUNTED, #NOTFOUND, #ERROR, or #ERRFILE. There is also no warning when these files are to be overwritten by the restore. The user can specify files that are in the negative list in a new BR*Tools parameter util_vol_nlist. For more information, see util_vol_nlist = (<nfile_name1>, <nfile_name2>, ) no_check [page 28]. Extended Output of Information on the Backup Utility Volume The following existing message optionally contains the backup volume name: #SAVED <backup_id> <file> [<backup_vol>] This is being extended to the #RESTORED message of the restore and the #BACKUP message of the inquire functions as follows, where <backup_vol> can contain up to 10 characters (one word): #RESTORED <backup_id> <file> [<backup_vol>] #BACKUP <backup_id> <file> [<backup_vol>] #BACKUP <backup_id> [<backup_vol>] We recommend you to generate the name of <backup_vol> so that the user can easily recognize the type of backup involved (for example, tape label, snapshot ID, clone ID). Therefore, we can describe this as generalized information on the backup volume. Therefore, in backup configurations where different types of backup are being created, we strongly recommend you to output volume information, although this is actually optional. 24

25 User-Defined Additional Options for BACKINT With the BR*Tools parameters util_vol_options and util_options you can define any additional options for the BACKINT call. See below: util_vol_options = < backint_volume_backup_options> [Page 29] and util_options = < backint_options> [page 29]. If these have been defined, BR*Tools puts them in the BACKINT command line after the standard options. For example, assume that the parameter util_vol_options is set: util_vol_options = "-server backserv1 -clone" This changes the BACKINT standard call as follows: Before: backint.exe -u NT1 -f backup -i D:\oracle\NT1\sapbackup\.bdvcyuxd.lst -t file_online -p initnt1.utl -c After: backint.exe -u NT1 -f backup -i D:\oracle\NT1\sapbackup\.bdvcyuxd.lst -t file_online -p initnt1.utl -c -server backserv1 -clone This new functionality enables you to pass call-specific control information to the BACKINT program. Make sure that the command syntax remains valid and that the additional options do not conflict with the standard options. To avoid conflicts with possible future extensions to the BACKINT interface, we recommend using complete keywords or capital letters for option names in the util_vol_options and util_options parameters. Optional Progress Information Generated by BACKINT BACKINT can now send information about the progress of the executing action to BR*Tools, using the following message: #DONE <percentage> where <percentage> is the percentage of work completed in the format nnn.dd (that is, to 2 decimal places), in the range 0.01 to For example: #DONE For reasons of clarity, we recommend that you send the progress information messages according to the following percentages: 1, 2, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 100 For example, when progress exceeds 40% for example, it reaches 41.30% you can issue a message that the job is 41.30% complete. Then you wait until progress exceeds the next threshold 45% in this example before issuing the next progress message. These progress information messages are only necessary for long-running actions, not for short actions such as mount, dismount, inquire and also backup/restore using a snapshot or clone. Optional Database Suspend and Resume for Disk Split If technically necessary, BACKINT can suspend the database for a disk split during an online backup. This is achieved by sending a message #SUSPEND DATABASE to BRBACKUP. The database resumes I/O after the #RESUME DATABASE message has been received. The logic used for this corresponds to the well-known hand-shaking logic in the functions file_online and volume_online and looks as follows: 1. BACKINT puts all files with the #BEGIN message in backup mode. All files to be backed up should be written to a single.switch.lis file. 25