4 Starting and Interacting with the RMAN Client

Entering RMAN Commands at the RMAN Prompt

When the RMAN client is ready for your commands, it displays the command prompt, as in this example:

RMAN> 

Enter commands for RMAN to execute. For example:

RMAN> CONNECT TARGET / 
RMAN> CONNECT CATALOG rman/password@inst2

RMAN> BACKUP DATABASE;

Most RMAN commands take a number of parameters and must end with a semicolon. Some commands, such as STARTUP, SHUTDOWN, and CONNECT, can be used with or without a semicolon.

When you enter a line of text that is not a complete command, RMAN prompts for continuation input with a line number. For example:

RMAN> BACKUP DATABASE
2> INCLUDE CURRENT 
3> CONTROLFILE
4> ;

Using Command Files with RMAN

For repetitive tasks, you can create a text file containing RMAN commands, and start the RMAN client with the @ argument, followed by a filename. For example, create a text file cmdfile1 in the current directory contained one line of text as shown here:

BACKUP DATABASE PLUS ARCHIVELOG;

You can run this command file from the command line as shown in this example, and the command contained in it is executed:

% rman TARGET / @cmdfile1

After the command completes, RMAN exits.

You can also use the @ command at the RMAN command prompt to execute the contents of a command file during an RMAN session. RMAN reads the file and executes the commands in it. For example:

RMAN> @cmdfile1

After the command file contents have been executed, RMAN displays the following message:

RMAN>  **end-of-file**

Unlike the case where a command file is executed from the operating system command line, RMAN does not exit.

Entering Comments in RMAN Command Files

The comment character in RMAN is a pound sign (#). All text from the pound sign to the end of the line is ignored. For example, the following command file contents backs up the database and archived redo log files and includes comments:

# Command file name: mybackup.rman
# The following command backs up the database
BACKUP DATABASE;
# The following command backs up the archived redo logs
BACKUP ARCHIVELOG ALL;

The following example shows that you can break a single RMAN command across multiple lines:

RMAN> BACKUP # this is a comment
2> SPFILE;

Starting backup at 30-APR-07
allocated channel: ORA_DISK_1
channel ORA_DISK_1: SID=118 device type=DISK
channel ORA_DISK_1: starting full datafile backup set
channel ORA_DISK_1: specifying datafile(s) in backup set
including current SPFILE in backup set
channel ORA_DISK_1: starting piece 1 at 30-APR-07
channel ORA_DISK_1: finished piece 1 at 30-APR-07
piece handle=/disk2/PROD/backupset/2007_04_30/o1_mf_nnsnf_TAG20070430T101234_33d8wgbj_.bkp tag=TAG20070430T101234 comment=NONE
channel ORA_DISK_1: backup set complete, elapsed time: 00:00:01
Finished backup at 30-APR-07
 
Starting Control File and SPFILE Autobackup at 30-APR-07
piece handle=/disk1/oracle/dbs/c-32126750-20070430-00 comment=NONE
Finished Control File and SPFILE Autobackup at 30-APR-07

Using Substitution Variables in Command Files

When running a command file, you can specify one or more values in a USING clause for use in substitution variables in a command file. In this way, you can make your command files dynamic.

As in SQL*Plus, &1 indicates where to place the first value, &2 where to place the second value, and so on. The substitution variable syntax is &integer followed by an optional period, for example, &1.3. The optional period is part of the variable and replaced with the value, thus enabling the substitution text to be immediately followed by another integer. For example, if you pass the value mybackup to a command file containing the variable &1.3, then the result of the substitution is mybackup3.

The following procedure explains how to create and use a dynamic shell script that calls a command file containing substitution variables.

To create and use a dynamic shell script:

1. Create an RMAN command file that uses substitution variables.

   The following example shows the contents of a command file named quarterly_backup.cmd. The script uses substitution variables for the name of the tape set, for a string in the FORMAT specification, and for the name of the restore point to be created.

   # quarterly_backup.cmd
   CONNECT SYS/password@prod1
   RUN
   {
     ALLOCATE CHANNEL c1
       DEVICE TYPE sbt
       PARMS 'ENV=(OB_MEDIA_FAMILY=&1)';
     BACKUP DATABASE 
       TAG &2 
       FORMAT '/disk2/bck/&1%U.bck'
       KEEP FOREVER 
       RESTORE POINT &3;
   }
   EXIT;
   

2. Create a shell script that you can use to run the RMAN command file created in the previous step.

   The following example creates a shell script named runbackup.sh. The example creates shell variables for the format and restore point name and accepts the values for these variables as command-line arguments to the script.

   #!/bin/tcsh
   # name: runbackup.sh
   # usage: use the tag name and number of copies as arguments
   set media_family = $argv[1]
   set format = $argv[2]set restore_point = $argv[3]
   rman @'/disk1/scripts/whole_db.cmd' USING $media_family $format $restore_point
   

3. Every quarter, execute the shell script created in the previous step, specifying the desired arguments on the command line.

   The following example runs the runbackup.sh shell script and passes it archival_backup as the media family name, bck0906 as the format string, and FY06Q3 as the restore point name.

   % runbackup.sh archival_backup bck0906 FY06Q3
   

Checking RMAN Syntax

You may want to test RMAN commands for syntactic correctness without executing them. Use the command-line argument CHECKSYNTAX to start the RMAN client in a mode in which it only parses the commands you enter and returns an RMAN-00558 error for commands that are not legal RMAN syntax.

RMAN> CONNECT TARGET *
2> BACKUP TAG 
Enter value for 1: mybackup
abc COPIES 
Enter value for 2: mybackup
abc
RMAN-00571: ===========================================================
RMAN-00569: =============== ERROR MESSAGE STACK FOLLOWS ===============
RMAN-00571: ===========================================================
RMAN-00558: error encountered while parsing input commands
RMAN-01009: syntax error: found "identifier": expecting one of: "integer"
RMAN-01008: the bad identifier was: mybackup
RMAN-01007: at line 2 column 25 file: /tmp/whole_db.cmd

Types of Database Connections Used with RMAN

To perform useful work, the RMAN client must connect to a target database, the database to be backed up or recovered. Depending on the task to be performed and your specific backup strategy, the RMAN client may also connect to the following other databases:

• The recovery catalog database, which provides an optional backup store for the RMAN repository in addition to the control file

• An auxiliary instance or auxiliary database, which may be a physical standby database, or an instance created for performing a specific task such as duplicating a database, transporting tablespaces without making the database read-only, or performing tablespace point-in-time recovery (TSPITR).

In the examples in this section, the generic values used have the meanings shown in Table 4-1.

Authentication for Database Connections

When connecting to a target or auxiliary database, you must have the SYSDBA privilege. You can connect as SYSDBA with a password file or with operating system authentication. Unlike SQL*Plus, RMAN does not require that you explicitly specify the SYSDBA keyword when connecting to a database. Because all RMAN database connections require SYSDBA privilege, RMAN always implicitly attempts to connect with this privilege.

If the target database uses password files, then you can connect using a password. Use a password file for either local or remote access. You must use a password file if you are connecting remotely as SYSDBA with a net service name.

If you connect to the database using operating system authentication, then you must set the environment variable specifying the Oracle SID. For example, to set the SID to trgt at the UNIX command line enter:

% ORACLE_SID=trgt; export ORACLE_SID

A SYSDBA privilege is not required when connecting to the recovery catalog. Note that you must grant the RECOVERY_CATALOG_OWNER role to the schema owner.

For automatic auxiliary instances, RMAN ensures that you have SYSDBA privilege when it sets up the instance.

Connecting to Databases from the Command Line

To connect to the target database from the operating system command line, enter the rman command followed by the connection information. Example 4-3 illustrates a connection to a target database that uses operating system authentication. The NOCATALOG option indicates that a recovery catalog will not be used in the session.

% rman TARGET / NOCATALOG

Example 4-4 illustrates a connection to a target database that uses Oracle Net authentication.

% rman TARGET SYS/password@trgt NOCATALOG   

Example 4-5 illustrates a connection that uses Oracle Net authentication for the target and recovery catalog databases.

% rman TARGET SYS/password@trgt CATALOG rman/cat@catdb   

You can also start RMAN without specifying NOCATALOG or CATALOG. If you do not specify NOCATALOG on the command line, and if you do not specify CONNECT CATALOG after RMAN has started, then RMAN begins to work in NOCATALOG mode the first time that you run a command that requires the use of the RMAN repository.

If you connect to the target database on the operating system command line, then you can begin executing commands after the RMAN prompt is displayed.

Connecting to the Databases from the RMAN Prompt

If you start RMAN without connecting to the target database, then you must issue a CONNECT TARGET command at the RMAN prompt to connect to a target database and begin performing useful work. Example 4-6 connects to a target database by means of operating system authentication.

% rman
RMAN> CONNECT TARGET /

Example 4-6 connects to a target database and recovery catalog from the RMAN prompt. The target connection uses operating system authentication, while the catalog database connection uses Oracle Net authentication.

% rman
RMAN> CONNECT TARGET /
RMAN> CONNECT CATALOG rman/password@catdb

Example 4-8 connects to the target database and recovery catalog database with database-level credentials.

% rman
RMAN> CONNECT TARGET SYS/password@trgt
RMAN> CONNECT CATALOG rman/password@catdb

Connecting to an Auxiliary Database

To use the DUPLICATE command, you need to connect to an auxiliary instance. To perform RMAN tablespace point-in-time recovery (TSPITR), you may also need to connect to an auxiliary instance.

The form of an auxiliary connection is identical to connect a target database connection, except that you use the AUXILIARY keyword instead of the TARGET keyword. Example 4-9 connects to a target database and auxiliary instance from the RMAN prompt.

% rman
RMAN> CONNECT TARGET /
RMAN> CONNECT AUXILIARY SYS/password@aux

Hiding Passwords When Connecting to Databases

If you create an RMAN command file which uses a CONNECT command with database level credentials (user name and password), then anyone with read access to this file can learn the password. There is no secure way to incorporate a CONNECT string with a password into a command file.

It is also possible, using the ps command under Linux or some similar command under other operating systems, to view command lines and arguments entered into the shell or other host operating system command line interpreter. Therefore, it is risky to invoke RMAN with a command line like this example:

% rman TARGET SYS/password@target

To connect to RMAN from the operating system command line and hide authentication information, you can start RMAN without connecting to databases, and then enter CONNECT commands at the RMAN prompt. You can also start RMAN without a password in the connect string, as in this example:

% rman TARGET SYS@target

RMAN will prompt for a password in such a case.

If you create an RMAN command file which uses a CONNECT command that includes authentication information, then RMAN does not echo the connect string when you run the command file with the @ command. This prevents connect strings from appearing in any log files that contain RMAN output.

For example, create a command file listbkup.rman which reads:

CONNECT TARGET SYS/password@target
LIST BACKUP;

Then execute this script by running RMAN with the @ command line option:

% rman @listbkup.rman

When the command file executes, RMAN replaces the connection string with an asterisk, as shown in the following output:

RMAN> connect target *
2> list backup;
3>
connected to target database: RDBMS (DBID=771530996)

using target database control file instead of recovery catalog

List of Backup Sets
===================
. . .

Diagnosing Connection Problems

When diagnosing errors RMAN encounters in connecting to the target, catalog and auxiliary databases, using SQL*Plus to connect to the databases directly can reveal underlying problems with the connection information or the databases.

RMAN> CONNECT TARGET SYS/password@target

SQL> CONNECT SYS/password@target AS SYSDBA

Executing Multiple RMAN Commands In Succession Through a Pipe: Example

This scenario assumes that the application controlling RMAN wants to run multiple commands in succession. After each command is sent down the pipe and executed and the output returned, RMAN will pause and wait for the next command.

To execute RMAN commands through a pipe:

1. Start RMAN by connecting to a target database (required) and specifying the PIPE option. For example, issue:

   % rman PIPE abc TARGET SYS/password@trgt
   

   You can also specify the TIMEOUT option, which forces RMAN to exit automatically if it does not receive any input from the input pipe in the specified number of seconds. For example, enter:

   % rman PIPE abc TARGET SYS/password@trgt TIMEOUT 60
   

2. Connect to the target database and put the desired commands on the input pipe by using DBMS_PIPE.PACK_MESSAGE and DBMS_PIPE.SEND_MESSAGE. In pipe mode, RMAN issues message RMAN-00572 when it is ready to accept input instead of displaying the standard RMAN prompt.

3. Read the RMAN output from the output pipe by using DBMS_PIPE.RECEIVE_MESSAGE and DBMS_PIPE.UNPACK_MESSAGE.

4. Repeat steps 2 and 3 to execute further commands with the same RMAN instance that was started in step 1.

5. If you used the TIMEOUT option when starting RMAN, then RMAN terminates automatically after not receiving any input for the specified length of time. To force RMAN to terminate immediately, send the EXIT command.

Executing RMAN Commands In a Single Job Through a Pipe: Example

This scenario assumes that the application controlling RMAN wants to run one or more commands as a single job. After running the commands that are on the pipe, RMAN will exit.

To execute RMAN commands in a single job through a pipe:

1. After connecting to the target database, create a pipe (if it does not already exist under the name ORA$RMAN_pipe_IN).

2. Put the desired commands on the input pipe. In pipe mode, RMAN issues message RMAN-00572 when it is ready to accept input instead of displaying the standard RMAN prompt.

3. Start RMAN with the PIPE option, and specify TIMEOUT 0. For example, enter:

   % rman PIPE abc TARGET SYS/password@trgt TIMEOUT 0
   

4. RMAN reads the commands that were put on the pipe and executes them by using DBMS_PIPE.PACK_MESSAGE and DBMS_PIPE.SEND_MESSAGE. When it has exhausted the input pipe, RMAN exits immediately.

5. Read RMAN output from the output pipe by using DBMS_PIPE.RECEIVE_MESSAGE and DBMS_PIPE.UNPACK_MESSAGE.

   See Also:

   Oracle Database PL/SQL Packages and Types Reference for documentation on the DBMS_PIPE package