Skip Headers

Oracle® Application Server Administrator's Guide 10g Release 3 (10.1.3) B25209-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 16 Oracle Application Server Recovery Manager

This chapter describes how to install, configure, and use the Oracle Application Server Recovery Manager.

It contains the following topics:

- How to Obtain OracleAS Recovery Manager

- How to Configure OracleAS Recovery Manager Manually

- Customizing OracleAS Recovery Manager for Your Configuration Files

- OracleAS Recovery Manager Usage Summary

## 16.1 How to Obtain OracleAS Recovery Manager

The OracleAS Recovery Manager is installed as part of an Oracle Application Server installation. It is located in the `Oracle_Home`/`backup_restore` directory. Table 16-1 lists the files that may reside in the `backup_restore` directory.

Table 16-1 OracleAS Recovery Manager Files

FileFoot 1 | Description
--- | ---
    bkp_restore.sh

    bkp_restore.bat
| A shell script used to run the manager on UNIX. A batch command file used to run the manager on Windows.
    config/config.inp
| The main configuration file that contains parameters for customizing OracleAS Recovery Manager for your environment. The `orainst_loc_path` field must be changed only if the instance is installed with the –invPtrLoc installer command-line option. It must be changed to reflect the nonstandard location of oraInst.loc.
    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 an instance backup. See Section 15.2.2, "Oracle Application Server Component Backup Input Files" for a list component configuration files.

Footnote 1 Paths are relative to the root of the OracleAS Recovery Manager directory.

See Also: Oracle Application Server Installation Guide for information about installing the Oracle Application Server.

## 16.2 How to Configure OracleAS Recovery Manager Manually

This section describes how to configure OracleAS Recovery Manager manually. 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 OracleAS Recovery Manager directory. It inserts a return character at the end of each line that may cause the manager to fail. Oracle recommends that you use a basic text formatter, such as Notepad, instead.

1. Prior to running the OracleAS Recovery Manager, set the `ORACLE_HOME` environment variable.

2. OracleAS Recovery Manager writes out log files and backup files, and you must specify the following directories to hold these. The default log file directory is `ORACLE_HOME``/backup_restore/logs`. Edit config.inp to create the following directories:

   1. Log file directory: This directory holds log files created by the manager. This directory should have several megabytes of space.

   2. Configuration file backup directory: This directory holds configuration file backups. This directory should have several hundred megabytes of space.

   Recommendations for creating these directories are as follows:

   - Create your backup directories on a file system on a separate disk and, if possible, a separate disk controller, than your Oracle Application Server Oracle home. This gives 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 and configuration file backup directory on `/disk1`:

     On Unix:

         mkdir -p /disk1/backups/log_files
         mkdir -p /disk1/backups/config_files
         cd /disk1/backups
         chmod 755 log_files config_files
         chown OracleAS_user log_files config_files

     On Windows:

         mkdir C:\backups\log_files
         mkdir C:\backups\config_files

3. Edit `config.inp` and modify the parameters as described in Table 16-2.

Table 16-2 Parameters in config.inp

Parameter | Value
--- | ---
`oracle_home` | Do not insert a value for this. Using the command-line interface, set ORACLE_HOME in the shell environment first.
`log_path` | Specify the full path of the log file directory. If the full path is not specified, the default log directory `ORACLE_HOME``/backup_restore/logs` is automatically created when the `-m configure` command is executed. If a `log_path` is specified in the `config.inp` file, but the specified directory does not exist, OracleAS Recovery Manager automatically creates the specified log directory whether or not the `-f` (force) option is used in the `-m configure` command. However, the configuration file backup directory is not automatically created unless the `-f` option is specified.
`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 it as `install_type=DO_NOT_SET`. This parameter is updated with the appropriate value for your installation when you run `bkp_restore.pl -m configure`.
`orainst_loc_path` | This parameter is used for UNIX platforms only. If the default path is overridden during installation, specify the full path of the directory where the `oraInst.loc` file exits. Otherwise, leave the parameter with the default value.
`plugin_config_files_list=DO_NOT_SET` | Do not update this parameter. It is updated when you enable components containing plug-in backup input files.

Configure OracleAS Recovery Manager by running it with the `-m configure` option, for example:

- For UNIX systems:

      ./bkp_restore.sh -m configure

- For Windows systems:

      bkp_restore.bat -m configure

- For TopLink on UNIX or Windows, after specifying the correct version of `perl.exe`, run:

      bkp_restore.pl -m configure

You are now ready to use OracleAS Recovery Manager.

## 16.3 Customizing OracleAS Recovery Manager for Your Configuration Files

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

### 16.3.1 How OracleAS Recovery Manager Works When Backing Up Configuration Files

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

1. Opens `config.inp` (unless another environment file was specified with the `-e` option) and retrieves `config_files_list`.

2. Attempts to open each file in `config_files_list` and exits with an error if it cannot open all of the files.

3. Examines the contents of `config_exclude_files.inp`. The manager will not attempt to back up the files listed in this file.

4. 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 manager 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 key file. For all other files that the manager does not find, a warning is issued and the backup continues.

   - If the key file does not exist, the manager 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.

5. The configuration files are stored in a jar file located in the directory specified by the `config_backup_path` parameter in the config.inp file:

       config_bkp_2004-05-10_18-33-10.jar

### 16.3.2 How to Customize OracleAS Recovery Manager

Since OracleAS Recovery Manager knows how to determine which configuration files exist in your installation, it is not necessary to customize OracleAS Recovery Manager. However, you may want to customize the manager 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 files, such as Oracle Application Server component specific log 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` parameter in `config.inp`, so there is no need to edit `config.inp`.

In some cases, OracleAS Recovery Manager might not be aware of additional files stored outside a typical directory structure. For example, in following cases you must edit `config_misc_files.inp` to ensure proper backup of the additional files:

- Virtual or nondefault paths defined in Oracle HTTP configuration files such as `httpd.conf` or `moddav.conf`. If you change these web server configuration files to point to other files or directories, you should consider making the new paths a part of the runtime backup.

- An application deployed to a OC4J container that uses files located outside the container directory. OracleAS Recovery Manager automatically backs up all the files located in the container directory. If your application uses any additional directories, you should consider them as part of configuration backups.

- Java Messaging Service (JMS) with the file-based persistence. The JMS runtime data (messages) are stored in physical files and should be a part of the backup process.

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 manager 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`.

## 16.4 OracleAS Recovery Manager Usage Summary

This section summarizes usage for OracleAS Recovery Manager.

It contains the following topics:

- Prerequisites for Running OracleAS Recovery Manager

- Syntax

- Usage Examples

- Purging Backups and Moving Them to Tertiary Storage

### 16.4.1 Prerequisites for Running OracleAS Recovery Manager

Before running OracleAS Recovery Manager:

- Log in as the user that installed Oracle Application Server.

- Make sure the `ORACLE_HOME` environment variable is set.

### 16.4.2 Syntax

The syntax for OracleAS Recovery Manager is:

On UNIX:

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

On Windows:

    bkp_restore.bat [-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 and configuration file directories to be created if they are required by the current command and do not exist.
`-n` Suppress prompts so the manager can run in batch mode.
`-o` Loss of Host Automation (LOHA) operation
`-s` Run in silent mode.
`-v` Run in verbose mode.
`-y` Used to enable components associated with plug-in backup input files.

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

Table 16-3 OracleAS Recovery Manager Modes and Arguments

Mode and Arguments | Description
--- | ---
`backup_config` | Performs a full configuration backup. The command performs the following operations: 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 the key file does not exist, it is treated as a fatal error. Otherwise, backs up all files in the list. If any other 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_instance_cold` | Performs a complete cold backup of the Oracle Application Server instance. The command performs the following operations: Stops all OPMN managed processes. Starts the OPMN administrative process. Checks all of the OPMN managed processes to ensure that the processes are stopped. If not, tries to stop them one more time. If the processes still cannot be stopped, issues a fatal error. Performs a full configuration backup. Starts all OPMN managed processes. Checks to ensure that all OPMN processes are running. If not, issues a warning message.
`backup_instance_cold_incr` | Performs an incremental cold backup of the Oracle Application Server instance. The command performs the following operations: Stops all OPMN managed processes. Starts the OPMN administrative process. Checks all of the OPMN managed processes to ensure that the processes are stopped. If not, tries to stop them one more time. If the processes still cannot be stopped, issues a fatal error. Performs incremental configuration backup. Starts all OPMN managed processes. Checks to ensure that all OPMN processes are running. If not, issues a warning message.
`backup_instance_online` | Performs an online backup of the Oracle Application Server instance.
`backup_instance_online_incr -1` `level number` | Performs an incremental online backup of the Oracle Application Server instance.
`configure` | Configures the manager. The command performs the following operation: Updates `config_files_list` and `install_type` in `config.inp` with the appropriate information for your installation.
`help` | Prints a usage message.
`list_backups` | Lists the configuration backups taken for the instance.
`list_instance_backups` | Lists instance level backups taken for the instance.
`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 does not 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. Deleted files or deleted directories are not listed in `list_changed_config`. Only modified files or directories containing modified files are listed.
`node_backup -o image_backup -P` `directory for the image archive` | Creates an image archive of the original host. The image includes the original Oracle home, oratab, central inventory and so forth, depending on the installation. On UNIX, this operation must be run as `root`.
`node_backup -o prepare` | Prepares the node for backup. Preparation includes discovering the operating system type, host name/ip, user/group id, install type, the location of the central inventory, oracle home locations if there are multiple of them, Windows registry, Windows service database scanning to find all services created for Oracle homes. The information is placed in a file to be used in node restoration. This mode also creates a config backup.
`node_restore -o inst_reconfigure -t config_bkp_timestamp` | Reconfigures the instance on the new host including IP changing, config backup, restore and so forth, depending upon the installation type.
`node_restore -o inst_register` | Registers the instance with the oratab and the central inventory. It also sets up the daemon start and stop script and so forth by running `root.sh`. On Windows, Windows services are created. It must be run as `root` on UNIX systems.
`node_restore -o sys_init` | Restores Oracle Universal Installer related metadata such as oratab (Unix), Windows registries (Windows) and central inventory. It should be run once only on the new host. It must be run as `root` on UNIX systems.
`restore_config` `[-t config_bkp_``timestamp``]` [`-n`] | Restores configuration files. The command performs the following operations: 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 manager in batch mode. For the process prerequisites, refer to the`backup_config` option. Do not run `restore_config` on multiple nodes in a J2EE cluster in parallel. Doing so will cause `restore_config` failures. Run `restore_config` on one node at a time.
`restore_instance -t` `timestamp` | Restores an instance of Oracle Application Server. If the timestamp argument is not specified, then a list of backup timestamps displays. The command performs the following operations: Stops all OPMN managed processes. Checks to verify that the OPMN processes have stopped. If OPMN processes cannot be stopped (maybe an `opmn.xml` file is missing), a file system restore is performed. Then, tries to stop the OPMN processes again. If the OPMN processes still cannot be stopped, issues a fatal error. Starts the OPMN administration process. Performs configuration restore. Starts all OPMN managed processes. Checks to ensure that all OPMN managed processes are up. If not, issues a warning message.

### 16.4.3 Usage Examples

This section contains usage examples for OracleAS Recovery Manager. The Unix command is listed first and then the Windows command.

- Configure the manager using the default `config.inp` file:

      bkp_restore.sh -m configure
      bkp_restore.bat -m configure

- Configure the manager using a configuration file called `myconfig.inp`:

      bkp_restore.sh -m configure -e myconfig.inp
      bkp_restore.bat -m configure -e myconfig.inp

- Perform an cold backup of an Oracle Application Server instance:

      bkp_restore.sh -m backup_instance_cold
      bkp_restore.bat -m backup_instance_cold

- Perform an incremental cold backup of an Oracle Application Server instance:

      bkp_restore.sh -m backup_instance_cold_incr
      bkp_restore.bat -m backup_instance_cold_incr

- Perform an online backup of an Oracle Application Server instance:

      bkp_restore.sh -m backup_instance_online
      bkp_restore.bat -m backup_instance_online

- Perform an online incremental backup of an Oracle Application Server instance:

      bkp_restore.sh -m backup_instance_online_incr
      bkp_restore.bat -m backup_instance_online_incr

- Restore an Oracle Application Server instance to its state at a particular time:

      bkp_restore.sh -m restore_instance -t 2004-09-21_06-12-45
      bkp_restore.bat -m restore_instance -t 2004-09-21_06-12-45

- Node backup preparation using Loss of Host Automation (LOHA)

      bkp_restore.sh -m node_backup -o prepare
      bkp_restore.bat -m node_backup -o prepare

- Create an image backup of the original host using LOHA

      bkp_restore.sh -m node_backup -o image_backup -P directory for image archive
      bkp_restore.bat -m node_backup -o image_backup -P directory for image archive

- Restore Oracle Universal Installer related metadata on the new host using LOHA

      bkp_restore.sh -m node_restore -o sys_init
      bkp_restore.bat -m node_restore -o sys_init

- Register the instance on the new host using LOHA

      bkp_restore.sh -m node_restore -o inst_register
      bkp_restore.bat -m node_restore -o inst_register

- Configure the instance on the new host using LOHA

      bkp_restore.sh -m node_restore -o inst_reconfigure -t config_bkp_timestamp
      bkp_restore.bat -m node_restore -o inst_reconfigure -t config_bkp_timestamp

### 16.4.4 Purging Backups and Moving Them to Tertiary Storage

OracleAS Recovery Manager saves records of successful backups in a catalog file (`data/catalog.txt`) in the `backup_restore` directory. Each backup is identified by a timestamp, which is also embedded in the filenames of jar files saved in the configuration file backup directory in the case of a instance or configuration only backup. If you delete all the`.jar` files corresponding to a timestamp or move them somewhere else, for example offline storage, although the catalog still contains a record of the timestamp, you will not see this record when you run `-m list_backups`, nor will you be able to restore using this timestamp as the `-t` value. This is the expected behavior.