5
Connecting to Databases with RMAN

This chapter gives detailed instructions for starting the Recovery Manager (RMAN) command-line interface and making database connections. This chapter contains these topics:

• Starting RMAN Without Connecting to a Database
• Connecting to a Target Database and a Recovery Catalog
• Connecting to an Auxiliary Database
• Hiding Passwords When Connecting to Databases
• Sending RMAN Output Simultaneously to the Terminal and a Log File
• Executing RMAN Commands Through a Pipe

Starting RMAN Without Connecting to a Database

You can start RMAN at the operating system command line without connecting to a database by issuing the RMAN command without any arguments. For example, enter:

% rman

If you did not specify the CMDFILE , SCRIPT or @ option at the command line, then RMAN displays the RMAN prompt:

RMAN>

After the RMAN prompt is displayed, you can issue further commands to connect to the target database, recovery catalog database, or auxiliary database.

If you start RMAN without specifying either CATALOG or NOCATALOG on the command line, then RMAN makes no recovery catalog connection. The first time a command is issued that requires the RMAN repository, RMAN performs the operation in NOCATALOG mode if you have not connected to a recovery catalog yet. After that point, the CONNECT CATALOG command can no longer be used without exiting and restarting the RMAN client.

Connecting to a Target Database and a Recovery Catalog

The following examples use the following sample connection data, and assume that a recovery catalog is being used.

Value	Description
SYS	User with SYSDBA privileges
oracle	The password for connecting as SYSDBA specified in the target database's password file
trgt	The net service name for the target database
rman	User that owns the recovery catalog schema. This is a user defined in the recovery catalog database that has been granted the RECOVERY_CATALOG_OWNER role.
cat	The password for connecting to the recovery catalog as user RMAN
catdb	The net service name for the recovery catalog database

Connecting to the Target Database and Recovery Catalog from the Command Line

You can specify either operating system or Oracle Net authentication information on the command line when you start the RMAN client.

This example shows how to use operating system authentication to connect to the target database and Oracle Net authentication for the recovery catalog:

% rman TARGET / CATALOG rman/cat@catdb

This example shows how to use Oracle Net authentication to connect to both the target database and the recovery catalog:

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

Connecting to the Target Database and Recovery Catalog from the RMAN Prompt

You can also start RMAN and connect to the target database from the RMAN prompt. The following example uses operating system authentication for the target database and Oracle Net authentication for the recovery catalog:

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

The following example uses Oracle Net password file authentication for the target database, which requires that the target database be using a password file, that defines the password for user SYS to be 'oracle'. Oracle Net authentication is also used for the recovery catalog.

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

Connecting to an Auxiliary Database

To use the DUPLICATE command, you need to connect to an auxiliary instance. To perform RMAN TSPITR, you may also need to connect to an auxiliary instance if, for example, you do not let RMAN manage the auxiliary instance for you.

If the auxiliary instance uses a password file for authentication, then you can connect using a password for either local or remote access. If you are connecting remotely through a net service name, then authentication through a password file is mandatory.

The following dummy values have been substituted into the following examples:

Value	Description
aux	The password for connecting as SYSDBA specified in the auxiliary database's orapwd file
auxdb	The net service name for the auxiliary database

Connecting to an Auxiliary Database from the Command Line

To launch RMAN connected to an auxiliary instance from the operating system command line, enter the following:

% rman AUXILIARY SYS/aux@auxdb

To connect to target, auxiliary, and recovery catalog databases, launch the RMAN client with these command line arguments:

% rman TARGET SYS/oracle@trgt AUXILIARY SYS/aux@auxdb CATALOG rman/cat@catdb 

Connecting to an Auxiliary Database from the RMAN Prompt

To launch RMAN without connecting to an auxiliary, and connect to the auxiliary database from the RMAN prompt, enter the following commands:

% rman
RMAN> CONNECT AUXILIARY SYS/aux@auxdb

To connect to the target, auxiliary, and recovery catalog databases from within RMAN, enter the following commands:

% rman
RMAN> CONNECT TARGET SYS/oracle@trgt
RMAN> CONNECT CATALOG rman/cat@catdb
RMAN> CONNECT AUXILIARY SYS/aux@auxdb

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.

Diagnosing Target and Auxiliary Database Connection Problems

RMAN always connects to target and auxiliary databases using the SYSDBA role. Thus, when using SQL*Plus to diagnose connection problems to the target or auxiliary databases, request a SYSDBA connection to reproduce RMAN's behavior.

For example, if the following RMAN command encountered connection errors:

RMAN> CONNECT target sys/oracle@target

you would reproduce the connection attempt with the SQL*Plus command:

SQL> CONNECT sys/oracle@target AS SYSDBA

Diagnosing Recovery Catalog Connection Problems

When RMAN connects to the recovery catalog database, it does not use the SYSDBA role. So, when you are using SQL*Plus to diagnose connection problems to the recovery catalog database, you must enter the catalog connect string exactly as it was entered into RMAN. Do not also specify AS SYSDBA.

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 Unix 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/oracle@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, 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/oracle@target
LIST BACKUP;

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

% rman @bkup.rman

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

Recovery Manager: Release 10.1.0.2.0 - Production

Copyright (c) 1995, 2003, Oracle.  All rights reserved.

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

using target database controlfile instead of recovery catalog

List of Backup Sets
===================
...rest of output omitted

Sending RMAN Output Simultaneously to the Terminal and a Log File

If you specify the LOG option at the command line, then RMAN displays command input but does not display the RMAN output. The easiest way to send RMAN output both to a log file and to standard output is to use the UNIX tee command or its equivalent on another operating system. For example:

% rman | tee rman.log
RMAN>

In this way, both input and output are visible within the RMAN command-line interface.

Executing RMAN Commands Through a Pipe

The RMAN pipe interface is an alternative method for issuing commands to RMAN and receiving the output. By using a pipe, RMAN can interface with the DBMS_PIPE PL/SQL package and avoid the operating system command shell altogether.

If the pipes are not already initialized, then RMAN creates them as private pipes. If you want to put commands on the input pipe before starting RMAN, be careful to first create the pipe by calling DBMS_PIPE.CREATE_PIPE. Whenever a pipe is not explicitly created as a private pipe, the first access to the pipe automatically creates it as a public pipe, and RMAN returns an error if it is told to use a public pipe.

RMAN does not permit the pipe interface to be used with public pipes, because they are a potential security problem. With a public pipe, any user who knows the name of the pipe can send commands to RMAN and intercept its output.

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.

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

   % rman PIPE abc TARGET SYS/oracle     @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/oracle@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, 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.

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/oracle@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: PL/SQL Packages and Types Reference for documentation on the DBMS_PIPE package and "RMAN Pipe Interface" for a brief overview of RMAN pipes