Skip Headers
Oracle® Database Backup and Recovery Reference
11g Release 1 (11.1)

Part Number B28273-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF



Use the RMAN command to start RMAN from the operating system command line.

See Also:

Oracle Database Backup and Recovery User's Guide to learn how to start RMAN from the command line


You must issue the RMAN command and any options at the operating system command line rather than at the RMAN prompt.

Usage Notes

The command name that you enter at the operating system prompt is operating system-dependent. For example, enter rman in lowercase on Linux and UNIX systems.

If you start RMAN without specifying either CATALOG or NOCATALOG on the operating system command line, then the RMAN session is effectively in NOCATALOG mode unless you execute a CONNECT CATALOG command. If you maintain a recovery catalog, then the best practice is to connect to the recovery catalog before performing RMAN operations.


On some platforms, connecting to a database at the operating system command line means that credentials are visible to other users on the system. For example, on many UNIX systems the output of the ps command can show the complete command line used to start RMAN, including any credentials provided on the command line. The CONNECT command avoids this problem.



Description of cmdline.gif follows
Description of the illustration cmdline.gif



Syntax Element Description
APPEND Causes new output to be appended to the end of the message log file. If you do not specify this parameter, and if a file with the same name as the message log file already exists, then RMAN overwrites it.
CHECKSYNTAX Causes RMAN to start in a mode in which commands entered are checked for syntax errors, but no other processing is performed (see Example 2-129). If used with a CMDFILE or @ argument, the RMAN client starts, checks all commands in the file, then exits. If used without specifying a command file, then RMAN prompts the user for input and parses each command until the user exits the RMAN client.

RMAN reports an RMAN-0558 error for each command that is not syntactically correct.

AUXILIARY connectStringSpec Specifies a connect string to an auxiliary database, for example, AUXILIARY SYS/oracle@dupdb.

See Also: connectStringSpec

CATALOG connectStringSpec Specifies a connect string to the database containing the recovery catalog, for example, CATALOG rman/rman@inst2.

See Also: SEND

CMDFILE filename Parses and compiles all RMAN commands in a file and then sequentially executes each command in the file. RMAN exits if it encounters a syntax error during the parse phase or if it encounters a run-time error during the execution phase. If no errors are found, then RMAN exits after the job completes.

If the first character of the filename is alphabetic, then you can omit the quotes around the filename. The contents of the command file should be identical to commands entered at the RMAN prompt.

Note: If you run a command file at the RMAN prompt rather than as an option on the operating system command line, then RMAN does not run the file as a single job. RMAN reads each line sequentially and executes it, only exiting when it reaches the last line of the script.

@filename Equivalent to CMDFILE.

   | integer}

Equivalent to options specified after USING syntax.
LOG filename Specifies the file where RMAN records its output, that is, the commands that were processed and their results. RMAN displays command input at the prompt but does not display command output, which is written to the log file. By default RMAN writes its message log file to standard output.

RMAN output is also stored in the V$RMAN_OUTPUT view, which is a memory-only view for jobs in progress, and in V$RMAN_STATUS, which is a control file view for completed jobs and jobs in progress.

The LOG parameter does not cause RMAN to terminate if the specified file cannot be opened. Instead, RMAN writes to standard output.

Note: The easiest way to send RMAN output both to a log file and to standard output is to use the Linux tee command or its equivalent. For example:

% rman | tee rman.log
MSGNO Causes RMAN to print message numbers, that is, RMAN-xxxx, for the output of all commands. By default, RMAN does not print the RMAN-xxxx prefix.
NOCATALOG Indicates that you are using RMAN without a recovery catalog.
SEND 'command' Sends a vendor-specific command string to all allocated channels.

See Also: Your media management documentation to determine whether this feature is supported, and SEND

PIPE pipe_name Invokes the RMAN pipe interface. RMAN uses two public pipes: one for receiving commands and the other for sending output. The names of the pipes are derived from the value of the PIPE parameter. For example, you can invoke the RMAN pipe interface with the following options: PIPE rpi TARGET SYS/pwd@tdb.

RMAN opens the following pipes in the target database:

  • ORA$RMAN_RPI_IN, which RMAN uses to receive user commands

  • ORA$RMAN_RPI_OUT, which RMAN uses to send all output

All messages on both the input and output pipes are of type VARCHAR2.

See Also: Oracle Database Backup and Recovery User's Guide to learn how to pass commands to RMAN through a pipe

SCRIPT script_name Specifies the name of a stored script.

After connecting to the target database and recovery catalog (which must be specified with the TARGET and CATALOG options), RMAN runs the named stored script from the recovery catalog against the target database. If both a global script and a local stored script exist on the target database with the name script_name, then RMAN runs the local script.

The single quotes around the stored script name are required when the script name either begins with a number or is an RMAN reserved word (see "RMAN Reserved Words"). You should avoid creating script names that begin with a number or that match RMAN reserved words.

See Also: CREATE SCRIPT for more details about stored scripts

TARGET connectStringSpec Specifies a connect string to the target database, for example, TARGET SYS/mypassword@inst1.

See Also: connectStringSpec

TIMEOUT integer Causes RMAN to exit automatically if it does not receive input from an input pipe within integer seconds. The PIPE parameter must be specified when using TIMEOUT.

See Also: Oracle Database Backup and Recovery User's Guide to learn how to pass commands to RMAN through a pipe

USING {string_or_identifier | integer} Specifies one or more values for use in substitution variables in a command file. As in SQL*Plus, &1 indicates where to place the first value, &2 indicate where to place the second value, and so on. Example 2-128 illustrates how to pass values specified in a USING clause to an RMAN command file.

The substitution variable syntax is &integer followed by an optional dot, for example, &1.3. The optional dot 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 that contains the substitution variable &1.3, then the result of the substitution is mybackup3.

See Also: EXECUTE SCRIPT to learn how to specify the USING clause when executing a stored script


Example 2-126 Connecting in Default NOCATALOG Mode

This example connects to the target database prod without specifying catalog options. Because CONNECT CATALOG is not run at the RMAN prompt, RMAN connects in default NOCATALOG mode when the first command requiring a repository connection is run.

% rman

Example 2-127 Connecting to an Auxiliary Instance

This example connects to target database prod and recovery catalog database catdb with net service names, and an auxiliary database instance with operating system authentication.

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

Example 2-128 Specifying Substitution Variables

Suppose that you want to create a Linux shell script that backs up the database. You want to use shell variables so that you can pass arguments to the RMAN backup script at run time. Substitution variables solve this problem. First, you create a command file named whole_db.cmd with the following contents:

cat > /tmp/whole_db.cmd <<EOF
# name: whole_db.cmd
CONNECT TARGET SYS/password@prod;

Next, you write the following Linux shell script, which sets csh shell variables tagname and copies. The shell script starts RMAN, connects to target database prod1, and runs whole_db.cmd. The USING clause passes the values in the variables tagname and copies to the RMAN command file at execution time.

# name:
# usage: use the tag name and number of copies as arguments
set tagname = $argv[1]
set copies = $argv[2]
rman @'/tmp/whole_db.cmd' USING $tagname $copies LOG /tmp/runbackup.out
# note that the preceding line is equivalent to:
# rman @'/tmp/whole_db.cmd' $tagname $copies LOG /tmp/runbackup.out

Finally, you execute the shell script from a Linux shell as follows to create two backups of the database with the tag Q106:

% Q106 2

Example 2-129 Checking the Syntax of a Command File

Suppose that you create command file backup_db.cmd as follows:

cat > /tmp/backup_db.cmd <<EOF

The following example checks the syntax of the contents of command file backup_db.cmd (sample output included):

% rman CHECKSYNTAX @'/tmp/backup_db.cmd'

Recovery Manager: Release - Production on Wed Jul 11 17:51:30 2007
Copyright (c) 1982, 2007, Oracle.  All rights reserved.
3> EXIT;
The cmdfile has no syntax errors
Recovery Manager complete.

Example 2-130 Running a Stored Script and Appending Output to a Message Log

This example connects to target database prod1 and recovery catalog database catdb and then runs stored script wdbb. RMAN writes output to message log /tmp/wdbb.log.

% rman TARGET SYS/password@prod CATALOG rman/password@catdb SCRIPT wdbb LOG /tmp/wdbb.log

Example 2-131 Invoking the RMAN Pipe Interface

This example invokes the RMAN pipe newpipe with a 90 second timeout option.

% rman PIPE newpipe TARGET SYS/password@inst1 TIMEOUT 90