To perform useful work, the RMAN client must connect to a database.

Table 4-1 describes the types of database connections that you can make with RMAN.

Users connecting with RMAN to a target or auxiliary database require either the SYSDBA or SYSBACKUP system privilege.

These privileges are not required when connecting to the recovery catalog. You must grant the RECOVERY_CATALOG_OWNER role to the catalog schema owner. Users can also connect to the recovery catalog using the VPC credentials that have been created by the recovery catalog owner.

The same authentication options that are available with SQL*Plus are available with RMAN. The most common ways to authenticate with the target and auxiliary databases are:

• Operating system authentication

  The prerequisites for connecting using operating system authentication are described in "Authentication Using the Operating System".

• Password file authentication

  The prerequisites for connecting using password file authentication are described in "Authentication Using a Password File".

Neither of these methods requires the database to be open. Operating system authentication is used only to connect locally. Password file authentication can be used to connect locally or remotely.

If you start RMAN without a connect string on the operating system command line, then you must issue a CONNECT TARGET command at the RMAN prompt to connect to a target database.

1. On the operating system command line, start the RMAN client without making a database connection.

   % rman
   RMAN>
   

2. At the RMAN prompt, enter one or more CONNECT commands.

RMAN> connect target /

RMAN> connect target "/ as sysdba"

RMAN> connect target "sbu@prod AS SYSBACKUP"

target database Password: password
connected to target database: PROD (DBID=39525561)

RMAN> connect target /
RMAN> connect catalog rco@catdb

recovery catalog database Password: password
connected to recovery catalog database

To connect to a target database from the operating system command line, enter the rman command followed by the connection information. You can begin executing commands after the RMAN prompt is displayed.

% rman TARGET / NOCATALOG

connected to target database: PROD (DBID=39525561)
using target database control file instead of recovery catalog
 
RMAN>

% rman TARGET sbu@prod NOCATALOG

target database Password: password
connected to target database: PROD (DBID=39525561)

RMAN>

% rman TARGET sbu@prod CATALOG rco@catdb

target database Password: password
connected to target database: PROD (DBID=39525561)
recovery catalog database Password: password
connected to recovery catalog database

RMAN>

You can connect the RMAN client to multitenant container databases (CDBs) and pluggable databases (PDBs).

This section contains the following topics:

• About Performing Operations on CDBs and PDBs

• Restrictions When Connected to a PDB

• Connecting as Target to the Root

• Connecting as Target to a PDB

You can make a database connection by creating an RMAN command file containing a CONNECT command..

cat > listbkup.rman << EOF
CONNECT TARGET /
LIST BACKUP;
EOF

% rman @listbkup.rman

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
===================
. . .

To use the DUPLICATE command, you must connect to an auxiliary instance. Performing tablespace point-in-time recovery (TSPITR) may also require a connection to an auxiliary instance.

% rman
RMAN> CONNECT TARGET /
RMAN> CONNECT AUXILIARY sbu@aux

auxiliary database Password: password
connected to auxiliary database: AUX (DBID=30472568)

% rman target / auxiliary sbu@aux

auxiliary database Password: password
connected to auxiliary database: AUX (DBID=30472568)

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

This section contains the following topics:

• Diagnosing Target and Auxiliary Database Connection Problems

• Diagnosing Recovery Catalog Connection Problems

When the RMAN client is ready for your commands, it displays the command prompt

RMAN> 

RMAN> CONNECT TARGET
RMAN> BACKUP DATABASE;

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

For repetitive tasks, you can create a text file containing RMAN commands, and start the RMAN client with the @ argument, followed by a file name.

BACKUP DATABASE PLUS ARCHIVELOG;

% rman TARGET / @cmdfile1

RMAN> @cmdfile1

RMAN>  **end-of-file**

The comment character in RMAN is a pound sign (#). All text from the pound sign to the end of the line is ignored.

# 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;

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

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.

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

   The following example shows the contents of a command file named quarterly_backup.cmd, which is run every quarter. 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 TARGET /
   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/quarterly_backup.cmd' USING $media_family $format $restore_point
   

3. 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

You can 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 that you enter and returns an RMAN-00558 error for commands that are not legal RMAN syntax.

You can check the syntax of RMAN commands either at the command line or in command files.

This example 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 pauses and waits for the next command.

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

   % rman PIPE abc TARGET /
   

   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 / 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.

This example 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 exits.

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 / 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