12 Oracle Application Server Backup and Recovery Tool

This chapter describes how to install, configure, and use the Oracle Application Server Backup and Recovery Tool (OracleAS Backup and Recovery Tool).

It contains the following topics:

What is the Oracle Application Server Backup and Recovery Tool?
How to Obtain the OracleAS Backup and Recovery Tool
How to Install the OracleAS Backup and Recovery Tool
How to Configure the OracleAS Backup and Recovery Tool
Customizing the Tool for Your Configuration Files
OracleAS Backup and Recovery Tool Usage Summary
Best Practices for Restoring and Recovering the Metadata Repository
Error Messages You Can Ignore

12.1 What is the Oracle Application Server Backup and Recovery Tool?

The Oracle Application Server Backup and Recovery Tool (OracleAS Backup and Recovery Tool) is a Perl script and associated configuration files you can use to backup and recover configuration files and the Metadata Repository in your Oracle Application Server environment. The types of files you can back up and recover using the tool are shaded in Figure 12-1.

Figure 12-1 Files You Can Backup and Recover Using OracleAS Backup and Recovery Tool

Description of the illustration asadm006.gif

The tool can be used in different ways, depending on your level of experience and requirements:

At a minimum, all users can refer to the tool for the list of Oracle Application Server configuration files that must be backed up
If you are new to backup and recovery, you can use the tool to perform configuration file and Metadata Repository backup and recovery
If you are experienced with backup and recovery, you can refer to the tool for guidance when setting up your own configuration file and Metadata Repository backup and recovery scripts

12.2 How to Obtain the OracleAS Backup and Recovery Tool

You can obtain the Oracle Application Server Backup and Recovery Tool from the "OracleAS RepCA and Utilities" CD-ROM. The tool is located on the CD-ROM in the utilities/backup directory.

See Also:

Oracle Application Server 10g Installation Guide for information about the "OracleAS RepCA and Utilities" CD-ROM

12.3 How to Install the OracleAS Backup and Recovery Tool

Before you install the OracleAS Backup and Recovery Tool, review the following notes:

You should install the tool multiple times—once for each Infrastructure and middle-tier installation in your environment. This is because you will customize the tool for each installation.

Note:

You cannot use the tool on a Metadata Repository installation that was created by running OracleAS RepCA in an existing database. Refer to Section 11.5, "Assumptions and Restrictions".

You must install the tool on the same host as its corresponding installation. You can install the tool in the Oracle home of its corresponding installation, or you can install it into a directory outside of the Oracle home.
The tool is a Perl script that requires a Perl 5.6.1 interpreter, or later. You can use the Perl interpreter that ships with Oracle Application Server 10g:
```
(UNIX) ORACLE_HOME/perl/bin/perl
(Windows) ORACLE_HOME\perl\5.6.1\bin\MSWin32-x86\perl.exe
```

To install the OracleAS Backup and Recovery Tool:

Log in as the user who installed Oracle Application Server.
Extract the contents of the backup_restore.tar file from the "OracleAS RepCA and Utilities" CD-ROM to your disk. You can install in the Oracle home, or in another directory outside of the Oracle home. For example, to install it in the Oracle home:
```
cd ORACLE_HOME
tar xvf CD_ROM/utilities/backup/backup_restore.tar
```
On UNIX, make sure the bkp_restore.pl file has execute permission, for example:
```
chmod 755 ORACLE_HOME/backup_restore/bkp_restore.pl
```
Familiarize yourself with the OracleAS Backup and Recovery Tool files, which are described in the Table 12-1. Instructions for editing the configuration files are in subsequent steps.

Table 12-1 OracleAS Backup and Recovery Tool Files

File^Foot 1	Description
`bkp_restore.pl`	The Perl script that you execute to perform backup and recovery operations
`config/config.inp`	The main configuration file that contains parameters for customizing the tool for your environment
`config/config_<component>_files.inp`	Component configuration files—each contains a list of configuration files for a particular component. These specify which files to back up when performing a configuration file backup.
`*.tmpl`	Templates for scripts for performing database backup and recovery operations using RMAN. When you initially configure the tool, a customized `.dat` file will be created from each `.tmpl` file.
`query_dbid.sql`	A SQL script called by the tool to initialize your configuration

^Footnote 1Paths are relative to the root of the OracleAS Backup and Recovery Tool directory.

12.4 How to Configure the OracleAS Backup and Recovery Tool

This section describes how to configure the OracleAS Backup and Recovery Tool. You must follow these steps for each installation in your environment.

Note for Windows Users:

Do not use a rich text editor, such as WordPad, when editing files in the Backup and Recovery Tool directory. It inserts a return character at the end of each line that may cause the tool to fail. Oracle recommends that you use a basic text formatter, such as Notepad, instead.

The tool writes out log files and backup files, and you must create the following directories to hold these.
1. Log file directory: (Middle tier and Infrastructure) This directory holds log files created by the tool. This directory should have several megabytes of space.
2. Configuration file backup directory: (Middle tier and Infrastructure) This directory hold configuration file backups. This directory should have several hundred megabytes of space.
3. Database backup directory: (Infrastructure only) This directory holds datafile and control files backups of the Metadata Repository, as well as archived redo logs. This directory should have several gigabytes of space.
Recommendations for creating these directories are as follows:
- Create your backup directories on a filesystem on a separate disk and, if possible, a separate disk controller, than your Oracle Application Server Oracle home. This will give you the best chance of recovering data in the event of a hardware failure.
- Make sure your backup directories are writable by the user that installed Oracle Application Server.
  
  For example, to create a log file directory, configuration file backup directory, and database backup directory on /disk1:
  
  On Unix:
```
mkdir -p /disk1/backups/log_files
mkdir -p /disk1/backups/config_files
mkdir -p /disk1/backups/db_files
cd /disk1/backups
chmod 755 log_files config_files db_files
chown OracleAS_user log_files config_files db_files
```
  On Windows:
```
mkdir C:\backups\log_files
mkdir C:\backups\db_files
mkdir C:\backups\config_files
```
Edit config.inp and modify the parameters as described in Table 12-2. Notice that some of the instructions are different depending on whether this is a middle-tier or Infrastructure installation.

Table 12-2 Parameters in config.inp

Parameter	Value
`oracle_home`	Specify the full path of the Oracle home.
`log_path`	Specify the full path of the log file directory.
`config_files_list`	Do not insert a value for this; leave it as `config_files_list=DO_NOT_SET`. This parameter will be updated with the appropriate list of configuration files for your installation when you run `bkp_restore.pl -m configure`.
`config_backup_path`	Specify the full path of the configuration file backup directory.
`install_type`	Do not insert a value for this; leave is as `install_type=DO_NOT_SET`. This parameter will be updated with the appropriate value for your installation when you run `bkp_restore.pl -m configure`.
`dbid`	Do not insert a value for this; leave it as `dbid=DO_NOT_SET`. For Infrastructure installations, this value will be updated when you run `bkp_restore.pl -m configure`. By default, the tool obtains the `dbid` from the Metadata Repository. Or, you can supply a `dbid` in special cases involving migrating a Metadata Repository from one host to another, such as for Disaster Recovery. For middle-tier installations, this value will stay untouched.
`pfile`	Middle-tier Installation: Leave this line commented out. Infrastructure: If desired, specify an alternate pfile to use when starting up the database. Otherwise, leave the line commented out and the default pfile will be used: (UNIX) `ORACLE_HOME`/dbs/initasdb.ora (Windows) ORACLE_HOME\database\initasdb.ora Be sure to leave the `pfile` entry commented out if you want to use the default because blank values are not allowed in this file.
`database_backup_path`	Middle-tier Installation: Do not insert a value for this; leave it as `database_backup_path=VALUE_NOT_SET.` Infrastructure: Specify the full path of the database backup directory.

Set the ORACLE_HOME environment variable to the Oracle Application Server Oracle home.
If this is an Infrastructure installation:
1. Set the ORACLE_SID environment variable to the Metadata Repository SID. The default is asdb.
2. Make sure the Metadata Repository is started.
Configure the tool by running it with the -m configure option, for example:
```
(UNIX) cd BACKUP_TOOL_DIR
./bkp_restore.pl -m configure
(Windows) perl bkp_restore.pl -m backup_cold
```
This updates parameters in config.inp and, in the case of an Infrastructure, creates customized .dat files, which are used to backup, restore, and recover the Metadata Repository.

You are now ready to use the OracleAS Backup and Recovery Tool.

12.5 Customizing the Tool for Your Configuration Files

As shipped, the OracleAS Backup and Recovery Tool backs up all of the Oracle Application Server configuration files that are necessary to reconstruct an Oracle Application Server installation.You can customize the tool to include any additional files that you would like to back up regularly, or to exclude any configuration files you do not want to back up.

12.5.1 How the Tool Works When Backing Up Configuration Files

Before you customize the tool, you should understand how it works. When you use the tool to back up your configuration files, it:

Opens config.inp (unless another environment file was specified with the -e option) and retrieves config_files_list.
Attempts to open each file in config_files_list and exits with an error if it cannot open all of the files.
Examines the contents of config_exclude_files.inp. The tool will not attempt to back up the files listed in this file.
Walks through each file in config_files_list and examines the first entry in each file. This entry is the key file. The key file is used to determine if the component exists in this installation.
- If the tool finds the key file, it knows the component is installed, and attempts to back up all of the entries in the file. It logs an error whenever it cannot find a file.
- If the key file does not exist, the tool does not attempt to back up any entries in the configuration file. It logs an error to the log file and skips to the next configuration file.

12.5.2 How to Customize the Tool

Since the tool knows how to determine which configuration files exist in your installation, it is not necessary to customize the tool. However, you may want to customize the tool by:

Adding Files to a Backup

You may want to add your own local configuration files or any other files you would like to back up regularly, such as log files
Excluding Files from a Backup

You may want to exclude files from being backed up

Adding Files to a Backup

To add a files to a backup, add entries to the config_misc_files.inp file as follows:

To specify a particular file:
```
${OH}/directorypath/file
```
To specify an entire directory:
```
${OH}/directorypath/
```
To use wildcards:
```
${OH}/directorypath/*.html
```

You can add as many entries as you like. The config_misc_files.inp file is always included in the config_files_list in parameter in config.inp, so there is no need to edit config.inp.

Note that you do not need to specify a key file in config_misc_files.inp.

Excluding Files from a Backup

You can exclude files from a backup in either of the following ways:

You can simply remove the file entry from its config_component.inp file.
If you have a situation where a config_component.inp file specifies an entire directory to back up, and you would like to exclude a specific file from that directory, you can add an entry for that file to config_exclude_files.inp. The tool will back up the entire directory except for the file you specify. You cannot specify directories or use wildcards in config_exclude_files.inp—only single file entries are allowed.

Note that you do not need to specify a key file in config_exclude_files.inp.

12.6 OracleAS Backup and Recovery Tool Usage Summary

This section summarizes usage for the OracleAS Backup and Recovery Tool.

It contains the following topics:

Prerequisites for Running the Tool
Syntax
Usage Examples

12.6.1 Prerequisites for Running the Tool

Before running the OracleAS Backup and Recovery Tool:

Log in as the user that installed Oracle Application Server.
Make sure the ORACLE_HOME environment variable is set.
If you are performing a database backup, make sure the ORACLE_SID environment variable is set. The default is asdb.
Change (cd) to the directory in which the tool resides.

12.6.2 Syntax

The syntax for the OracleAS Backup and Recovery Tool is:

bkp_restore.pl [-defsv] -m mode [args]

It accepts the following options:

-d Print a trace without executing.
-e Specify an environment file (default is config.inp).
-f Force log file, database backup, and configuration file directories to be
created if they are required by the current command and do not exist.
-s Run in silent mode.
-v Run in verbose mode.

Use the -m option to specify which mode to run. Some modes take arguments. Table 12-3 describes the OracleAS Backup and Recovery Tool modes and their arguments. All modes and arguments are case-sensitive.

Table 12-3 Oracle Application Server Backup and Recovery Tool Modes and Arguments

Mode and Arguments	Description
`backup_cold`	Performs a complete cold backup of the Metadata Repository. Opens `config.inp` (or the alternate file specified with the `-e` option) and retrieves `log_path`. Shuts down the database, starts it in mounted mode, but does not open it. Performs a backup of the datafiles and control files using RMAN. The commands are in `backup_cold.dat`. Stores the backup in the directory specified in `backup_cold.dat`. (This is usually set to the `database_backup_path` in `config.inp`.) Stores a log file in `log_path`. Opens the database.
`backup_cold_incr` `-l` `incr_backup_level`	Performs an incremental backup of the Metadata Repository. Works the same as `backup_cold`, except: The `-l` option specifies the increment level (`0` - `4)`. Uses the `backup_cold_incr``level``.dat file` There are two types of incremental backups, cumulative and differential. The tool uses the default type, which is differential. For more information, refer to Oracle9i Recovery Manager User's Guide in the Oracle9i Documentation Library.
`backup_config`	Performs a full configuration file backup. Opens `config.inp` (or the alternate file specified with the `-e` option) and retrieves `config_files_list`, `config_backup_path`, and `log_path`. Attempts to open each file in `config_files_list`. Exits with an error if it cannot open all of the files. For each file in `config_files_list`, checks if the first entry (the key file) exists. If it does not exist, assumes this component does not exist and moves on to the next file. Otherwise, backs up all files in the list. If any files do not exist, logs an error and continues. Excludes files listed in `config_exclude_files.inp`. When finished, stores the backup in `config_backup_path/config_bkp_``timestamp`. If any errors are encountered, creates a log file in `log_path``/config_bkp_``timestamp`.
`backup_config_incr`	Performs an incremental configuration file backup. Works the same as `backup_config`, except: Backs up all configuration files that have changed since the last full or incremental configuration file backup.
`backup_online`	Performs an online backup of the Metadata Repository. Opens `config.inp` (or the alternate file specified with the `-e` option) and retrieves `log_path`. Assumes the database is open. Performs a backup of the datafiles and control files using RMAN. The commands are in `backup_online.dat`. Stores the backup in the directory specified in `backup_online.dat`. (This is usually set to the `database_backup_path` in `config.inp`.) Stores a log file in `log_path`. Leaves the database open.
`backup_online_incr` `-l` `incr_backup_level`	Performs an incremental online backup of the Metadata Repository. Works the same as `backup_online`, except: The `-l` option specifies the increment level (`0` - `4)`. Uses the `backup_online_incr``level``.dat file` There are two types of incremental backups, cumulative and differential. The tool uses the default type, which is differential. For more information, refer to Oracle9i Recovery Manager User's Guide in the Oracle9i Documentation Library.
`configure` `[-i` `dbid``]`	Configures the tool. When using this on an Infrastructure, make sure the Metadata Repository is up before you run this command. Updates `config_files_list` and `install_type` in `config.inp` with the appropriate information for your installation. If using this on an Infrastructure, updates the configuration file with the database id (`dbid`) and creates customized `.dat` files from the database backup `.tmpl` files. By default, it queries the Metadata Repository for the `dbid`. If you use the `-i` option, you can supply the `dbid` (this is used for migrating the Metadata Repository from one node to another, such as for Disaster Recovery).
`configure_nodb`	Same as "`configure`" but does not perform the Infrastructure configuration. Note: You should use "`configure`" for all middle-tier and Infrastructure installations; "`configure_nodb`" applies to disaster recovery strategies described in Oracle Application Server 10g High Availability Guide.
`help`	Prints a usage message.
`list_changed_config`	Lists any configuration files that have changed since the last full or incremental backup. This command checks the modification date of each file; it doesn't check the actual contents of the file. It writes the list of files to a log file and prints the name of the log file.
`restore_config` `[-t config_bkp_``timestamp``]` [`-n`]	Restores configuration files. Opens `config.inp` (or the alternate file specified with the `-e` option) and retrieves `config_backup_path` and `log_path`. If the `-t` option is supplied and it is the timestamp from a full backup, it restores that full backup. If the `-t` option is supplied and it is the timestamp from an incremental backup, it restores the full backup and all incremental backups up to and including the specified incremental backup. If the `-t` option is not supplied, displays a list of configuration file backups in `config_backup_path` and exits. You can then rerun the command and supply one of these files with the `-t` option. Restores all files from the configuration file backup to the Oracle home, preserving owner, group, permissions, and timestamp. If any errors are encountered, creates a log file in `log_path``/config_rst_``timestamp`. The `-n` option suppresses prompts so you can use the tool in batch mode.
`restore_db` `[-u` `timestamp``][-c]`[`-n`]	Restores and recovers the Metadata Repository from the available cold and online backups. Opens `config.inp` (or the alternate file specified with the `-e` option) and retrieves `log_path`. Restores the control files and datafiles, and performs recovery using RMAN. The commands are in `restore_db.dat`. Stores a log file in `log_path`. Leaves the database open. By default, this command restores and recovers the database to its most recent state. You can use the `-u` option to restore and recover the database to its state at a particular point in time. For example: `bkp_restore.pl -m restore_db -u` 7/26/2003_13:45:06 By default, this command does not restore the control file. You can use the `-c` option to restore the control file. If you use the `-u` or `-c` option, be sure to do a full backup right away because all past backups are invalidated. The `-n` option suppresses prompts so you can use the tool in batch mode. Refer to Section 12.7, "Best Practices for Restoring and Recovering the Metadata Repository" for more information.

12.6.3 Usage Examples

This section contains usage examples for the OracleAS Backup and Recovery Tool.

Configure the tool using the default config.inp file:
```
bkp_restore.pl -m configure
```
Configure the tool using a configuration file called myconfig.inp:
```
bkp_restore.pl -m configure -e myconfig.inp
```
Perform a full configuration file backup:
```
bkp_restore.pl -v -m backup_config
```
Perform a full configuration file backup using an environment file called myconfig.inp:
```
bkp_restore.pl -v -m backup_config -e myconfig.inp
```
Perform an incremental configuration file backup:
```
bkp_restore.pl -v -m backup_config_incr
```

Restore configuration files.

bkp_restore.pl -m restore_config -t config_bkp_2003-02-27_13-45

Perform a full cold backup of the Metadata Repository:
```
bkp_restore.pl -m backup_cold
```
Perform a level 2 incremental cold backup of the Metadata Repository:
```
bkp_restore.pl -m backup_cold_incr -l 2
```
Perform an full online backup of the Metadata Repository:
```
bkp_restore.pl -m backup_online
```
Perform a level 0 incremental online backup of the Metadata Repository:
```
bkp_restore.pl -m backup_online_incr -l 0
```
Restore the Metadata Repository to its most recent state:
```
bkp_restore.pl -m restore_db
```
Restore the Metadata Repository to its state at a particular time:
```
bkp_restore.pl -m restore_db -u 7/26/2003_13:45:06
```

12.7 Best Practices for Restoring and Recovering the Metadata Repository

This section describes best practice tips for using the OracleAS Backup and Recovery Tool to restore and recover the Metadata Repository. It contains the following sections:

Restoring and Recovering the Metadata Repository to the Same Host

Restoring and Recovering the Metadata Repository to a New Host

Note:

This best practices in this section use the OracleAS Backup and Recovery Tool. There are many other options available for restoring and recovering a database when you use the RMAN command directly. For more information, refer to Oracle9i Recovery Manager User's Guide in the Oracle9i documentation library.

12.7.1 Restoring and Recovering the Metadata Repository to the Same Host

This section covers several circumstances under which you may need to restore and recover the Metadata Repository to the same host:

Corrupted or Lost Datafile
Corrupted or Lost Control File
Point-in-time Recovery

Corrupted or Lost Datafile

If a datafile is corrupted or lost, you can use the following command to restore from the latest backup and perform a full recovery:

bkp_restore.pl -m restore_db

Corrupted or Lost Control File

If a control file is corrupted or lost, you can use the following command to restore a control file backup, restore the datafiles, and perform a full recovery:

bkp_restore.pl -m restore_db -c

When you use the -c option, it restores the control file. This causes entries for tempfiles in locally-managed temporary tablespaces to be removed. You must add a new tempfile to the TEMP tablespace, or Oracle will display error ORA-25153: Temporary Tablespace is Empty.

To add a tempfile to the TEMP tablespace:

SQL> alter tablespace "TEMP" add tempfile 'ORACLE_HOME/oradata/GDB/temp01.dbf' size 5120K autoextend on next 8k maxsize unlimited;

GDB is the first part of the global database name.

Note that when you restore a control file, the tool performs an "alter database open resetlogs." This invalidates all backups and archivelogs. You should immediately perform a complete cold backup of the Metadata Repository, which will serve as the new baseline for your subsequent partial online backups.

Point-in-time Recovery

If you lost configuration files in your middle-tier or Infrastructure installation and restored those, you may want to restore the database to the same point-in-time as the configuration file backup. You can do this using the following command:

bkp_restore.pl -m restore_db -u timestamp

You can specify any time between the time of your first backup and the current time, as long as none of the online redo logs were compromised. If any online redo logs are missing or corrupted, the latest time that can be specified is the time at which the last backup was made.

Note that when you do point-in-time recovery, the tool performs an "alter database open resetlogs." This invalidates all backups and archivelogs. You should immediately perform a complete cold backup of the Metadata Repository, which will serve as the new baseline for your subsequent partial online backups.

12.7.2 Restoring and Recovering the Metadata Repository to a New Host

When you restore the Metadata Repository to a new host (with the same hostname and IP address), the new host will not have the online redo logs that existed on the original host. Therefore, you cannot perform a full recovery—RMAN would give an error stating that it cannot find a certain log file (the online redo log file). Instead, you should do a point-in-time recovery using a time sometime between the first and most recent backup. You can do this using the following command:

bkp_restore.pl -m restore_db -c -u timestamp

If this command returns an error and the log shows that the datafiles were restored and recovered, then issue an "alter database open resetlogs" and the database will be opened in a consistent state. If no datafiles were restored and recovered, it is most likely an early timestamp was specified and you should retry the command with a later timestamp.

To add a tempfile to the TEMP tablespace:

SQL> alter tablespace "TEMP" add tempfile 'ORACLE_HOME/oradata/GDB/temp01.dbf' size 5120K autoextend on next 8k maxsize unlimited;

GDB is the first part of the global database name.

Note that whenever you restore the Metadata Repository to a new host, the control file will be restored from backup. This means that an "alter database open resetlogs" is always done, which invalidates all backups and archivelogs. You should immediately perform a complete cold backup of the Metadata Repository, which will serve as the new baseline for your subsequent partial online backups.

12.8 Error Messages You Can Ignore

This section lists OracleAS Backup and Recovery Tool error messages you can ignore for certain configurations.

When performing a configuration file backup in a Metadata Repository-only installation, you can ignore the following error message:

Could not copy ORACLE_HOME/Apache/Apache/conf/osso/osso.conf to BACKUP_DIR/Apache/Apache/conf/osso/osso.conf: No such file or directory

When performing a configuration file backup in a J2EE and Web Cache installation that does not use Identity Management, you can ignore the following error message:
```
Could not copy ORACLE_HOME/Apache/Apache/conf/osso/osso.conf to BACKUP_DIR/Apache/Apache/conf/osso/osso.conf: No such file or directory
```
When performing a configuration file backup in an OracleAS TopLink installation in which you have not yet opened the Mapping Workbench and created a project, you can ignore the following error message:
```
Could not copy ORACLE_HOME/toplink/config/workbench.xml to BACKUP_DIR/toplink/config/workbench.xml: No such file or directory
```