Topics | How To | Related Topics
RMAN backup and restore scripts for the Oracle iDataAgent can be submitted from the Command Line Interface using the Qoperation backup and Qoperation restore commands. This feature allows custom RMAN scripts to be submitted to the system through argument files in order to take advantage of the CommServe's job management and reporting capabilities as well as media reservation, multi-streaming and storage policies.
Submitting RMAN scripts through the Command Line Interface offers the following distinct advantages over submitting them from RMAN:
Consider the following when submitting an RMAN backup script to run through the Command Line Interface:
Before setting up the RMAN backup script to run through the Command Line Interface, you must first create an On Demand Instance in the CommCell Console on the Oracle iDataAgent for which you intend to run scripts. See Create an On Demand Instance for step-by-step instructions.
When an On Demand Data Protection operation for multiple instances is in progress, the specific instance name on which the operation is currently run will be displayed in the Job Controller window.
To run an RMAN backup script using the Command Line Interface, run the Qoperation backup command on the client and provide the path to the custom RMAN script(s) in the command line parameter (-af) argument file. The CommServe will then run the job as a regular Oracle iDataAgent backup, using the custom RMAN scripts instead of the subclient properties to generate an RMAN script for the backup operation. You can also view the RMAN log output for the running qoperation command from the Job Details dialog in the Job Controller window. For step-by-step instructions on viewing the RMAN Log for running Oracle jobs, see View the RMAN Log of an Active Job.
We recommend that separate scripts be provided for data and logs because only one data type can be passed through the argument file (i.e., data or log). The data type is used by the system to mark the archive files created by the backup as "DATA" or "LOG" in the CommServe Database. Therefore, archive files will be marked as either DATA or LOG even though scripts containing both data and logs may be included in the job. Although you can combine data and logs scripts in the same job, however, it is a best practice to run data and logs scripts in separate jobs. This design also allows the drive reservation and re-try mechanism to function more efficiently.
One or more of the following script parameter options must be contained in the argument file for the backup job:
Name of the instance to be backed up, and the name of the file that contains the RMAN backup script. One instance can be backed up in the argument file. If there are more than one instance present in the argument file backup job will fail, more then one script can be run for an instance in the script.
| For Oracle on Windows, do not enter a space after a comma in the argument file or the job will fail. |
Backup data type used by the system to mark the associated backup archive files in the CommServe Database. The datatype can be specified as either DATA or LOG.
Name of the Storage Policy to be used for the RMAN backup job.
Number of streams to reserve for the RMAN backup job.
The following parameter options can be included in the argument file:
Location where the RMAN backup output file will be saved and the name of the output file. By default, an output file backup.out is created in the job results directory. You can change the name of the output file as well as the location using this parameter. In order to include the JOB ID in the output file name, you need to set the sQcmd_Bkp_RmanLogFile registry key.
When you want to include the JOB ID, make sure that you do not specify any output file name in the rmanlogfile parameter. The output file name with JOB ID is defined in the registry key and will be used to create the file in the output file location specified in the rmanlogfile parameter. For example, in the rmanlogfile parameter, specify the following:
[rmanlogfile]
/usr/temp1
Here, temp1 is the directory and not the file name.
In the sQcmd_Bkp_RmanLogFile registry key, specify the file name as follows:
sQcmd_Bkp_RmanLogFile TSTLOG_<JOBID>.out
Now the file TSTLOG_<JOBID> will be created in the temp1 folder.
If specified, the backup will only start if all the specified number of streams are available. If not specified, the default behavior is to reserve as many streams as possible at the start of the backup. If additional streams become available during the backup, they will be allocated dynamically.
Do not multiplex the same streams of one Job ID. Different jobs will still be multiplexed.
If specified, the backup will not use the connect string and catalog values specified in the Instance Properties (Details) tab in the CommCell Console. Instead, the user defined connect string and catalog connect values specified in the RMAN script will be used for the On Demand backup operation. The user should make sure to enter the correct connect string value for the instance to be backed up.
For example,
Connect target <sql_user_name>/<sql_user_password>@<SID_name>
Connect catalog <catalog_user_name>/<catalog_user_password>@<catalog_db_name>
or
Connect target /
Connect catalog <catalog_user_name>/<catalog_user_password>@<catalog_db_name>
It is not required to provide the Connect catalog.
Name of the media agent to be used for the backup job.
Name of the library to be used for the backup job.
Name of the drivepool in the library to be used for the backup job.
Name of the scratchpool in the library to be used for the backup job.
The drivepool and scratchpool parameters are applicable only if a tape library is used for the RMAN backup. The drivepool and scratchpool names can be given along with the library name followed by a backslash (/) or itself alone.
User can use this option to write the job description.
For example,
allocate channel cvlt1 type 'sbt_tape'
allocate channel cvlt2 type 'sbt_tape'
---
---
---
allocate channel cvlt5 type 'sbt_tape'
Data Aging for Oracle On Demand backup jobs uses days/time, and ignores cycles, as the determining factor for pruning the data. Therefore, once the retention time criteria has been met, all data (for both data and logs) is pruned that was backed up using the storage policy specified in the RMAN script that was run through the Command Line Interface.
Consider the following when developing a storage policy strategy for Oracle On Demand backups:
See Data Aging for more information.
Ability to set a completion percentage of oracle CLI jobs and to make this percentage viewable in the CommCell Browser using the qoperation job control command.
Restarting an Oracle On Demand backup job for multiple scripts for the same instance will cause the instance, whose backup was interrupted, to be backed up again from the beginning of the script which was running. Because of this restart behavior, if the archive files for that instance were successfully backed up before the restart, they will be backed up again after the restart. As a result, Job Manager may count the data size of archive files twice for the instance that the Oracle On Demand backup job was restarted from. Therefore, the size of data reported as backed up for this job (in the Job Details and Backup Job History) will reflect the duplicate size of the archive files that were backed up twice for that instance. The scripts should be updated to prevent this behavior before resuming the job.
See Restarting Jobs for more information.
You can suspend an Oracle On Demand backup job from the CommCell Console. For more information, see Job Preemption Control.
For Oracle On Demand backup jobs, in cases where multiple instances are backed up that are not all in the same mode, Job Manager will report the backup type as either Full (when the first instance in the backup script is in OPEN mode) or as Offline Full (when the first instance in the backup script is in MOUNTED mode).
For an Oracle On Demand backup job, the following reports or screens will list the names of all the instances on which the backup job was performed:
Consider the following when submitting an RMAN restore script to run through the Command Line Interface:
To run an RMAN restore script using the Command Line Interface, run the Qoperation restore command on the client and provide the path to custom RMAN script in the command line parameter (-af) argument file. You can also view the RMAN log output for the running qoperation command from the Job Details dialog in the Job Controller window. Save as Script and qoperation restore Command Line Interface for Oracle Table Level restore are also supported. See Options used by the Oracle iDataAgent and Table Restores for more information.
The following script parameter option must be contained in the argument file for the restore job:
[oraclerestorescript]
<filename>
Name of file that contains RMAN script for restore.
Location where the RMAN restore output file will be saved and the name of the output file. By default, an output file restore.out is created in the job results directory. You can change the name of the output file as well as the location using this parameter. In order to include the JOB ID in the output file name, you need to set the sQcmd_Rst_RmanLogFile registry key.
When you want to include the JOB ID, make sure that you do not specify any output file name in the rmanlogfile parameter. The output file name with JOB ID is defined in the registry key and will be used to create the file in the output file location specified in the rmanlogfile parameter. For example, in the rmanlogfile parameter, specify the following:
[rmanlogfile]
/usr/temp1
Here, temp1 is the directory and not the file name.
In the sQcmd_Rst_RmanLogFile registry key, specify the file name as follows:
sQcmd_Rst_RmanLogFile TSTLOG_<JOBID>.out
Now the file TSTLOG_<JOBID> will be created in the temp1 folder.
Name of the media agent to be used for the restore job.
Name of the library to be used for the restore job.
Name of the drivepool in the library to be used for the restore job.
Name of the scratchpool in the library to be used for the restore job.
The drivepool and scratchpool parameters are applicable only if a tape library is used for the RMAN restore. The drivepool and scratchpool names should be given along with the library name followed by a backslash (/) or itself alone.
If specified, the restore operation will not use the connect string and catalog values specified in the Instance Properties (Details) tab in the CommCell Console. Instead, the user defined connect string and catalog connect values specified in the RMAN script will be used for the On Demand restore operation. The user should make sure to enter the correct connect string value for the instance to be restored.
For example,
Connect target <sql_user_name>/<sql_user_password>@<SID_name>
Connect catalog <catalog_user_name>/<catalog_user_password>@<catalog_db_name>
or
Connect target /
Connect catalog <catalog_user_name>/<catalog_user_password>@<catalog_db_name>
It is not required to provide the Connect catalog.
Provided below are sample entries to run RMAN backup and restore scripts from the Command Line Interface.
qoperation backup -c client1 -a Q_ORACLE -af /argfile1.txt -t Q_FULL
qoperation restore -sc client1 -a Q_ORACLE -i instance1 -af /argfile2.txt
Provided below are sample contents of an argument file for backup and another for restore.
[instancescripts]
instance1,/rman_data_backup1.scr
instance2,/rman_data_backup2.scr
[datatype]
DATA
[sp]
oracle_data_storage_policy
[streamcount]
4
[oraclerestorescript]
/rman_restore.scr
This section provides supplementary information on the qoperation move command, including some examples of how it can be used to facilitate the efficient use of resources within a CommCell.
The Qoperation move command is supported for the Oracle iDataAgent to move an instance from one client or cluster node to another client or node within a CommCell. This feature provides the following benefits:
To illustrate the usefulness of the qoperation move command for Oracle, the following use cases are provided below.
CompanyA has multiple Oracle instances located on various client cluster nodes, and wants to streamline Command Line Interface backup operations by running just one job to back up all of these instances on one client with one job. To accomplish this, the backup administrator decides to move Oracle instances InstanceA1 and InstanceA2 from ClientA to ClientB (which has the same operating system and is already hosting instances InstanceB1 and InstanceB2 on a cluster).
Using the following Qoperation move commands, the backup administrator was able to move the desired instances from ClientA to ClientB:
qoperation move -sc ClientA -a Q_ORACLE -i InstanceA1 -dc ClientB
qoperation move -sc ClientA -a Q_ORACLE -i InstanceA2 -dc ClientB
After moving InstanceA1 and InstanceA2 from ClientA to ClientB, the resulting configuration for ClientB now contains InstanceA1, InstanceA2, InstanceB1, and InstanceB2.
In order to back up all of these instances in one job, the backup administrator then creates an On Demand Instance in the CommCell Console, and sets up an argument file containing scripts for backing up all of these instances on ClientB following the guidelines discussed in Backup Considerations for running RMAN scripts using the Command Line Interface.
After completing the above setup tasks, the backup administrator executed the following qoperation backup command from the Command Line Interface to perform a full backup of all instances on ClientB:
qoperation backup -c ClientB -a Q_ORACLE -af /argfile1.txt -t Q_FULL
The end result is that all instances on ClientB were able to be backed up as one On Demand backup job, which made the process quicker and more efficient for the company.
CompanyB has several Oracle databases configured to run as virtual servers all hosted by the same physical computer within a cluster. They operate numerous clusters under this type of configuration at their site. Under certain conditions any one of these virtual servers can fail over, creating a situation where the instance data needs to be ported over to a different physical computer until the conditions that caused the failover can be rectified. The backup administrator decides to move the 4 instances from the virtual server that failed over to a new physical computer that has the same operating system. To do this, the backup administrator executes the following move commands to re-locate these instances (VM1 through VM4) from one client in the CommCell (ClusterServer1) to another client in the CommCell (ClusterServer2):
qoperation move -sc ClusterServer1 -a Q_ORACLE -i VM1 -dc ClusterServer2
qoperation move -sc ClusterServer1 -a Q_ORACLE -i VM2 -dc ClusterServer2
qoperation move -sc ClusterServer1 -a Q_ORACLE -i VM3 -dc ClusterServer2
qoperation move -sc ClusterServer1 -a Q_ORACLE -i VM4 -dc ClusterServer2
By moving these instances to a new physical host, the interruption to production database activities from the failover was minimized, and provided the technicians with the time they needed to identify and correct the issues that caused the failover on the original host.
NOTES