restore

Purpose

Use the restore command to create a file system restore request. File system restore operations are distinct from database restore operations, which are initiated by Recovery Manager (RMAN).

You can use the restore command to perform catalog-based or raw restore operations. In a catalog-based restore, you browse the catalog for the objects to be restored. When you have located their names and selected the instances, you can restore the objects. In a raw restore, you must have independent knowledge of the secondary storage location (volume ID and backup image file number) of a backup. You can either restore all data in the backup or specify an individual file or directory.

A restore request is held locally in obtool until you run the restore command with the --go, --gocatalog, or --goraw option, at which time Oracle Secure Backup converts all restore requests into jobs and sends them to the Oracle Secure Backup scheduler.

Prerequisites

If you have specified that the restore run in privileged mode, or if you are restoring files to an NDMP-accessed host, then you must have the right to perform restores as privileged user to use the restore command. Otherwise, you must have the right to perform restores as self.

Usage Notes

obtool uses the host variable to determine the name of the host whose backups are being restored. The default value for host is the name of the host on which obtool is running. You can set the host variable with the set or cd command.

Syntax

Syntax 1

Use the following syntax to restore data by browsing the Oracle Secure Backup catalog. See "Semantics for Syntax 1".

restore::=

res•tore [ --tohost/-h hostname ] [ --device/-d drivename ]
[ --privileged/-g | --unprivileged/-G ]
[ --replaceexisting/-e | --keepexisting/-E ]
[ --replaceinuse/-u | --keepinuse/-U ] [ --incremental/-i ]
[ --noposition/-X ] [ --priority/-p schedule-priority ]
[ --select/-s data-selector[,data-selector]... ]
[ --obtaropt/-o obtar-option ]... [ --go | --gocatalog | --goraw ]
{ pathname [ --aspath/-a pathname ] }...

Syntax 2

Use the following syntax for raw restore operations. See "Semantics for Syntax 2".

restore::=

res•tore --raw/-R [ --tohost/-h hostname ] [ --device/-d drivename ]
[ --privileged/-g | --unprivileged/-G ]
{ --filenumber/-F filenumber }
{ --vid/-v vid[,vid ]... } [ --tag/-t tag[,tag]... ]
[ --replaceexisting/-e | --keepexisting/-E ]
[ --replaceinuse/-u | --keepinuse/-U ] [ --incremental/-i ]
[ --priority/-p schedule-priority ]
[ --obtaropt/-o obtar-option ]... [ --go | --gocatalog | --goraw ]
{ --all/-A | { pathname [--aspath/-a pathname ] [ --position/-x position ] }... }

Semantics

Semantics for Syntax 1

--tohost/-h hostname

Specifies the name of the host machine to which you want to restore data.

--device/-d devicename

Specifies a library or tape drive used to perform the restore operation. Refer to "devicename" for the rules governing device names.

--privileged/-g

Specifies that the restore operation should run in privileged mode.

On UNIX systems, a privileged restore job runs under the root user identity. On Windows systems, the job runs under the same account identity as the Oracle Secure Backup service on the Windows client.

--unprivileged/-G

Specifies that the restore operation should run in unprivileged mode (default).

An unprivileged restore job runs under the UNIX user or Windows account identity specified in the mkuser command. Access to file system data is constrained by the rights of the UNIX user or Windows account having this identity.

--replaceexisting/-e

Overwrites existing files (default).

--keepexisting/-E

Does not overwrite existing files.

--replaceinuse/-u

Replaces in-use files with those from the backup image. Windows deletes each in-use file when the last user closes it. This option is available on Windows only.

--keepinuse/-U

Leaves in-use files unchanged (default). This option is available on Windows only.

--incremental/-i

Directs NAS data servers to apply incremental restore rules. This option applies only to NAS data servers that implement this feature. This option does not apply to file system backups created with obtar.

Normally, restore operations are additive: each file and directory restored from a full or an incremental backup is added to its destination directory. If files have been added to a directory since the most recent Oracle Secure Backup backup, then a restore operation does not remove the newly added files.

When you specify --incremental, NAS data servers restore each directory to its state during the last incremental backup. Files that were deleted prior to the last incremental backup are deleted by the NAS data service when restoring this incremental backup.

For example, assume you make an incremental backup of /home, which contains file1 and file2. You delete file1 and make another incremental backup of /home. After a normal restore of /home, the directory would contain file1 and file2; after an NDMP incremental restore of /home, the directory would contain only file2.

--noposition/-X

Indicates that Oracle Secure Backup should not use available position data to speed the restore operation. You might use this option if position data is corrupted: for example, you make a copy of a tape with obcopy, but the desired file ends up at a different physical position on the tape.

--priority/-p schedule-priority

A schedule priority you assign to a restore. Refer to "schedule-priority" for a description of the schedule-priority placeholder.

--select/-s data-selector ...

Filters data based on the specified data-selector. Refer to "data-selector" for the data-selector placeholder.

--obtaropt/-o obtar-option ...

Specifies obtar options. For example -J enables debug mode and provides more details in the restore transcript. See the section entitled "obtar Options" for details on obtar options.

--go

Releases all queued restore requests to the Oracle Secure Backup scheduler.

--gocatalog

Releases queued restore requests from a backup catalog to the Oracle Secure Backup scheduler.

--goraw

Releases queued raw restore requests to the Oracle Secure Backup scheduler. A raw restore request does not use backup catalog data.

pathname ...

Specifies the path name obtained by browsing the backup catalog for files that you backed up. If you do not specify --aspath, then Oracle Secure Backup restores the backup to the same path. If pathname does not exist on the host to which you are restoring, then Oracle Secure Backup creates it.

For example, assume that you browse the backup catalog for brhost2 and locate the /home directory, which you want to restore. The restore /home command restores the backup to the /home directory on brhost2.

--aspath/-a pathname

Specifies an alternative path name where Oracle Secure Backup can restore the files. For example, if you want to restore a backup of /home to /tmp/home, then specify restore /home --aspath /tmp/home.

Note that if pathname does not exist on the host to which you are restoring, then Oracle Secure Backup creates it.

Semantics for Syntax 2

Options that are also found in Syntax 1 are not described in this section.

--raw/-R

Specifies a raw restore operation, which is a restore operation that does not use an Oracle Secure Backup catalog. You must specify the identity (volume ID or barcode) of the tape volumes to which the file system objects were backed up as well as the backup image file number in which they are stored.

--filenumber/-F filenumber

Specifies the file number on the tape where the backup is located. Refer to "filenumber" for a description of the filenumber placeholder.

--vid/-v vid ...

Selects backups based on volume ID. Refer to "vid" for a description of the vid placeholder.

--tag tag ...

Selects backups based on the volume tag (barcode).

--all/-A

Restores all data in the backup.

pathname ...

Specifies the absolute path name of the file or directory that you backed up. If you do not know the absolute path names for the files when they were backed up, then you can use obtar -tvf to find them or restore an entire backup image. If you do not specify --aspath, then Oracle Secure Backup restores the backup to the same path.

Note that if pathname does not exist on the host to which you are restoring, then Oracle Secure Backup creates it.

--aspath/-a pathname

Specifies an alternative path name where Oracle Secure Backup can restore the files. For example, if you want to restore a backup of /private/lashdown to /tmp/private/lashdown, then specify restore /private/lashdown --aspath /tmp/private/lashdown.

Note that if pathname does not exist on the host to which you are restoring, then Oracle Secure Backup creates it.

--position/-x position ...

Specifies the position of the data on the tape.

Example

Example 2-119 displays the latest backup image of the /home/data directory stored in the Oracle Secure Backup catalog. The restore command submits the restore request to the scheduler with priority 1. Oracle Secure Backup runs the job and restores the data.

ob> set host brhost2
ob> cd /home/data
ob> ls
bin/  c_files/  tree/
ob> lsbackup latest
      Backup       Backup  Volume            Volume       File Sect Backup
   Date and Time       ID  ID                Tag             #    #  Level
2005/03/28.11:17:02     2  VOL000003         ADE201          1    1      0
ob> restore --select latest --priority 1 --go /home/data
Info: raw restore request 1 submitted; job id is admin/6.
ob> lsjob admin/6
Job ID           Sched time  Contents                       State
---------------- ----------- ------------------------------ ---------------------------------------
admin/6          none        restore 1 item to brhost2      completed successfully at 
                                                            2005/03/29.16:34

Example 2-120 submits a raw restore request to the scheduler. The request specifies that the /home/data directory should be restored from volume VOL000003. Oracle Secure Backup runs the job and restores the data.

ob> restore --raw --filenumber 1 --vid VOL000003 /home/data
ob> restore --go
Info: raw restore request 1 submitted; job id is admin/76.
ob> lsjob admin/7
Job ID           Sched time  Contents                       State
---------------- ----------- ------------------------------ ---------------------------------------
admin/7          none        restore 1 item to brhost2      completed successfully at
                                                            2005/03/29.17:00