RMAN Pipe Interface & Concepts
Alireza KamraniUsing the RMAN Pipe Interface
The RMAN pipe interface is an alternative method for issuing commands to RMAN and receiving the output from those commands. Using this interface, it is possible to write a portable programmatic interface to RMAN.
With the pipe interface, RMAN obtains commands and sends output by using the DBMS_PIPE PL/SQL package instead of the operating system shell. The pipe interface is invoked by using the PIPE command-line parameter for the RMAN client. RMAN uses two private 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 RMAN with the following command:
% rman PIPE abc TARGET /
RMAN opens the two pipes in the target database: ORA$RMAN_ABC_IN, which RMAN uses to receive user commands, and ORA$RMAN_ABC_OUT, which RMAN uses to send all output back to RMAN.
All messages on both the input and output pipes are of type VARCHAR2.
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.
If the pipes are not initialized, then RMAN creates them as private pipes. If you want to put commands on the input pipe before starting RMAN, you must 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.
Note:
If multiple RMAN sessions can run against the target database, then you must use unique pipe names for each RMAN session. The DBMS_PIPE.UNIQUE_SESSION_NAME function is one method that you can use to generate unique pipe names.
Possible used for the pipes interface are:
• Applications coded to automatically invoke one or more backup and recovery functions to achieve their design objectives
• Third party tools which whish to provide their own interface to RMAN
• DBA tools that wish to incorporate some RMAN functionality
Executing Multiple RMAN Commands in Succession Through a Pipe: Example
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.
To execute RMAN commands through a pipe:
• 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
• 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.
• Read the RMAN output from the output pipe by using DBMS_PIPE.RECEIVE_MESSAGE and DBMS_PIPE.UNPACK_MESSAGE.
• Repeat Steps 2 and 3 to execute further commands with the same RMAN instance that was started in Step 1.
• 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 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.
To execute RMAN commands in a single job through a pipe:
• After connecting to the target database, create a pipe (if it does not already exist under the name ORA$RMAN_pipe_IN).
• 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.
• Start RMAN with the PIPE option, and specify TIMEOUT 0. For example, enter:
% rman PIPE abc TARGET / TIMEOUT 0
• 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.
• Read RMAN output from the output pipe by using DBMS_PIPE.RECEIVE_MESSAGE and DBMS_PIPE.UNPACK_MESSAGE.
A Practical Scenario
The RMAN Pipe Interface allows Oracle sessions to send RMAN commands to a running RMAN process using Oracle’s internal DBMS_PIPE mechanism.
It’s mainly used for controlling RMAN from inside PL/SQL rather than through OS scripts.
So instead of typing commands in the RMAN CLI, you:
• Start RMAN with PIPE <name>
• Send commands into that pipe using DBMS_PIPE.PACK_MESSAGE and SEND_MESSAGE
• RMAN executes those commands
• Read results via DBMS_PIPE.RECEIVE_MESSAGE
Step 1: Start RMAN in Pipe Mode
From the OS:
$rman PIPE DEMO_PIPE TARGET / TIMEOUT 600
This launches RMAN and creates two private Oracle pipes:
• ORA$RMAN_DEMO_PIPE_IN
• ORA$RMAN_DEMO_PIPE_OUT
RMAN will wait for incoming PL/SQL commands for up to 600 seconds.
You can confirm it’s waiting via:
SELECT sid, event FROM v$session_wait WHERE event LIKE '%pipe%';
You’ll see RMAN waiting on "pipe get handle" or similar events.
Step 2: Create the PL/SQL Procedure RMAN_CMD
CREATE OR REPLACE PROCEDURE rman_cmd(cmd VARCHAR2) AS
in_pipe_name VARCHAR2(2000) := 'ORA$RMAN_DEMO_PIPE_IN';
out_pipe_name VARCHAR2(2000) := 'ORA$RMAN_DEMO_PIPE_OUT';
v_info VARCHAR2(255);
v_status INTEGER;
BEGIN
DBMS_OUTPUT.PUT_LINE('Begin RMAN command: ' || cmd);
-- Clean old pipe data
v_status := DBMS_PIPE.RECEIVE_MESSAGE(out_pipe_name, 0);
WHILE v_status = 0 LOOP
DBMS_PIPE.UNPACK_MESSAGE(v_info);
v_status := DBMS_PIPE.RECEIVE_MESSAGE(out_pipe_name, 10);
END LOOP;
-- Send the RMAN command
DBMS_PIPE.PACK_MESSAGE(cmd);
v_status := DBMS_PIPE.SEND_MESSAGE(in_pipe_name);
-- Wait for RMAN output
v_status := 0;
WHILE v_status = 0 OR v_status = 1 LOOP
v_status := DBMS_PIPE.RECEIVE_MESSAGE(out_pipe_name, 30);
IF v_status = 0 THEN
DBMS_PIPE.UNPACK_MESSAGE(v_info);
DBMS_OUTPUT.PUT_LINE(v_info);
IF v_info LIKE '%RMAN-00572%' OR v_info LIKE '%Recovery Manager complete%' THEN
EXIT;
END IF;
END IF;
END LOOP;
END;
/
This procedure:
• Cleans any stale messages from previous runs.
• Sends your command to RMAN.
• Reads back RMAN’s textual output line-by-line.
• Displays or logs it.
Step 3: Execute Real RMAN Commands from SQL*Plus
Now, in the same SQL*Plus session, you can send actual RMAN commands to the RMAN process:
EXEC rman_cmd('SHOW ALL;');
EXEC rman_cmd('CONFIGURE RETENTION POLICY TO RECOVERY WINDOW OF 3 DAYS;');
EXEC rman_cmd('BACKUP SPFILE;');
EXEC rman_cmd('LIST BACKUP OF TABLESPACE SYSTEM;');
EXEC rman_cmd('LIST BACKUP SUMMARY;');
EXEC rman_cmd('REPORT NEED BACKUP;');
EXEC rman_cmd('CONFIGURE RETENTION POLICY CLEAR;');
EXEC rman_cmd('EXIT;');
Step 4: What Happens in the Background
Each call:
• Sends the text (e.g. "BACKUP SPFILE;") through the pipe to RMAN.
• RMAN executes the command.
• RMAN writes back the results (progress, logs, errors) to the OUT pipe.
• Your PL/SQL procedure prints these results in real time.
A Real-World Use Case
To automate backups or monitoring from PL/SQL (without relying on external OS scripts).
You should follow these steps:
1- Schedule RMAN to start with a private pipe (as a background process or job):
$nohup rman PIPE AUTO_BACKUP TARGET / TIMEOUT 1800 &
2- Inside Oracle, define your procedure (like rman_cmd) to send commands.
3-Create a scheduler job:
BEGIN
DBMS_SCHEDULER.CREATE_JOB (
job_name => 'DB_AUTO_BACKUP',
job_type => 'PLSQL_BLOCK',
job_action => q'[
BEGIN
rman_cmd('BACKUP DATABASE PLUS ARCHIVELOG DELETE INPUT;');
END;
]',
start_date => SYSTIMESTAMP,
repeat_interval => 'FREQ=DAILY;BYHOUR=1',
enabled => TRUE
);
END;
/
• Store and analyze RMAN output in a log table for reporting or alerts.
This approach keeps backup orchestration inside Oracle, using RMAN’s own engine but controlled via PL/SQL.
Monitoring and Troubleshooting
To check current RMAN pipe sessions:
SELECT name, type, pipe_size
FROM v$db_pipes
WHERE name LIKE '%RMAN%';
Important Notes :
Privileges: Grant EXECUTE ON DBMS_PIPE only to DBA/specific service account.
Security: Use private pipes only to increase security. Public pipes are blocked by default in 21c.
RMAN lifecycle: The RMAN process must be running before you send commands.
Timeout: If RMAN doesn’t receive any new command within the TIMEOUT window, it will exit automatically.
Parallel RMANs: You can run multiple RMAN instances with different pipe names, e.g., RMAN21_DEV_PIPE, RMAN21_PRD_PIPE.
#############################
