obtar

B obtar

The primary user interfaces for file-system backup and restore operations are the Oracle Secure Backup Web tool and obtool. The underlying engine that Oracle Secure Backup uses to back up and restore data is obtar. You can use the obtar command-line interface directly, although this practice is recommended only for advanced users.

This appendix contains these sections:

obtar Overview

obtar is a descendent of the original Berkeley UNIX tar(1) command. The obtar command-line interface conforms to the POSIX 1003.2 standards for UNIX command lines as follows:

Options are single letters preceded with a dash, as in -c.
If an option requires an argument, then it follows the option and can be separated from the option with a space, as in ‐c argument.
Multiple options can be combined after a single dash if no multiple options require an argument. If only one option requires an argument, then this option must appear last in the group. For example, if -c takes an argument, then you might specify ‐vPZc argument.

Table B-1 explains the basic obtar modes. The description of each mode includes the most common options. "obtar Options" describes additional options.

Table B-1 obtar Modes

Option	Description
obtar -c	Creates a one-time backup image of the directories and files specified on the command line.
obtar -x	Restores directories and files.
obtar -t	Lists the contents for a backup image.
obtar -zz	Displays a list of the backup images contained on the volume.

If you back up directories and files so that the necessary Oracle Secure Backup catalog data is generated, such as when using the -G, or -N options, then you can use obtool or the Oracle Secure Backup Web tool to browse the catalog and restore the files. If you do not generate the catalog files, however, then you can still perform a raw restore operation.

Optimizing Your Use of obtar

This section describes ways you can optimize your use of obtar, and provides information about some more advanced backup features of obtar.

This section includes the following topics:

Using tar with Backup Images Created by obtar

By default, obtar generates backup images that are fully compatible with tar. This section offers tips for using tar with backup images created with obtar.

When you create a backup image with obtar -g, obtar creates several files in the backup image that provide information about the backup image. obtar knows that these file are special and never extracts them from the backup image as actual files. To tar, the files appear to be ordinary files; when you use tar to extract a backup image, tar creates several files that have the prefix ###. When you restore a backup image with obtar -x, obtar does not create these files.

You can use any of the following obtar options and still maintain compatibility with tar:

-b, -B, -c, -f, -h, -l, -m, -t, -v, -x

When you are using tar to extract a backup image that spans multiple volumes, note that each section of a backup image that spans multiple volumes is a valid tar file. obtar can correctly extract the contents of the backup image, but tar encounters an early end-of-file condition after it extracts the first section of the backup image. At this point, you have extracted only the first part of the data for the file that continues across the volume break. To restore the file completely, you must do the following:

Move the first file fragment to a location that is not overwritten as you continue the extraction.
Load the next volume and continue the extraction. The second file fragment is extracted.
Use the UNIX cat command to append the second file fragment to the first file fragment to obtain the complete file. For example:
```
cat first_frag second_frag > complete_file
```
Delete the file fragments.

Backing Up and Restoring Raw File Systems

When obtar encounters a special file while backing up a tree, it usually writes only the special file name and attributes to the backup image. If a special file is mentioned at the top level of the backup tree, however, either explicitly or with a wildcard, then obtar backs up the file name, attributes, and contents. n this section, special files includes both block special files and character special files.

Note:

Oracle Secure Backup does not support the backup or restore of the contents of character special files.

For example, the following command creates a backup image consisting of all the special file names in the /dev directory, but neither opens nor reads any special file:

obtar -cvf tape0 /dev

On the other hand, the following command causes obtar to open /dev/sd0a, /dev/sd13a, /dev/sd13b, and so on and write the entire contents of the underlying raw file systems to the backup image:

obtar -cvf tape0 /dev/sd0a /dev/sd13*

Because this form of access bypasses the native Linux or UNIX file system, you can use it to back up raw file systems that contain data other than Linux or UNIX data, for example, a disk partition containing a database.

Because obtar has no idea which blocks are used or unused on the raw file system, the entire file system is always saved. This is different from a backup using the vendor-supplied Linux or UNIX file system, which saves only blocks in use.

When restoring data to a raw file system, the size of the file system to which you are restoring must be at least the size of the file system that was backed up. When restoring a raw file system, all data currently on the file system is lost. It is totally overwritten by the data from the backup image.

To restore a raw file system, the raw file system must have been formatted using mkfs, mkvol, or a similar tool, and the special file referring to the raw file system must exist. Otherwise, the data is restored as a normal file.

Note:

Never back up or restore a mounted file system. If a file system is mounted, then activity by other processes might change the file system during the backup or restore, causing it to be internally inconsistent.

Backing Up Raw Partitions

You can use obtool to back up raw partitions. The raw file system must not be mounted during the backup. You can back up the block device file by including the path of the device file in a dataset.

To back up raw partitions:

Create a dataset for the raw partition.

For example, you can create a dataset named rawpart.ds as follows:
```
include host brhost2
{
  include path /dev/sda3
}
```
Back up the partition.

The following obtool command makes a backup using the dataset created in the previous step:
```
ob> backup -D rawpart.ds --restriction lib1 --go
```

Restoring Raw Partitions

You can use obtool to restore raw partitions. The raw file system must not be mounted during the restore operation.

To restore raw partitions:

Use obtool to set the host to which you want to restore:

For example, run the cd command as follows to set the host to brhost2:
```
ob> cd --host brhost2
```
Restore the partition.

The following obtool command restores partition /dev/sda3:
```
ob> restore --select latest /dev/sda3 –-go
```

Changing Criteria for Incremental Backups

When obtar decides if a file is to be included in an incremental backup, it usually uses the mtime for the file, which is the time at which the contents of the file were last modified. If a file was added to a directory by using mv or cp -p, then it might not get backed up because its modified time is not changed from those of the original copy of the file. You can get around this problem by telling obtar to use ctime, which is the status change time, rather than mtime as the criterion for inclusion in an incremental backup. The status change time of a file is the time at which a file's inode was last modified.

Using ctime results in the selection of all files that would have been selected using mtime plus those that have been moved or copied into the directory. Specify this option by specifying -Xuse_ctime on the command line. For a scheduled backup, you can include -Xuse_ctime in the backupoptions policy.

There is a drawback to using -Xuse_ctime. When using the mtime criterion, obtar resets the atime of each file after it has been backed up. atime is the last accessed time. The act of backing up a file does not change the atime of the file. If you are using ctime as the selection criterion, then obtar cannot reset the time last accessed because it would reset the file's change time, thus turning every incremental backup into a full backup. In other words, specifying -Xuse_ctime also turns on -Xupdtu.

The important points are as follows:

If -Xuse_ctime is not specified, then incremental test is mtime, atimes are left unchanged, and moved files might be missed.
If -Xuse_ctime is specified, then incremental test is ctime, atimes reflect time of backup, and moved files are caught.

Backing Up Across Mount Points

A local mount point mounts a local file system. A remote mount point is a local mount for a file system accessed over the network. By default, obtar does not cross local or remote mount points unless the mount point is explicitly specified.

You can control mount point behavior with the following obtar options:

-Xchkmnttab

By default, obtar performs a stat(2) operation to determine whether a file represents a mount point. If a remotely mounted file system is down or not responding, then the stat(2) operation can cause the obtar process to hang.

The -Xchkmnttab option causes obtar to consult local mount table /etc/mnttab before performing these stat(2) operations and to skip directories determined to be remote mount points. Local mount points are not skipped.

You can specify -Xchkmnttab either on the command line or in the backupoptions policy. The -Xchkmnttab option is overridden by -Xcrossmp.
-Xcrossmp

The -Xcrossmp option directs obtar to cross all mount points even if the -Xchkmnttab option is specified. You can specify the -Xcrossmp option on the command line or in the backupoptions policy.

obtar -c

Purpose

Use obtar -c to create a single backup image. You might use obtar -c to perform an on-demand backup or to back up data to a volume that you could transport to another site.

For NDMP backups, obtar uses the default NDMP backup type set for the data service. You can override this setting by specifying a backup type at the host level or by using the NDMP policy. obtar verifies that the user-specified backup type is valid for the data service that is used for the backup operation. However, the comparison used by obtar is case-sensitive and recognizes only lowercase values. Thus, if you specify the backup type using upper case, obtar does not recognize it as a valid backup type and uses the default NDMP backup type for the backup operation.

If the user ID (UID) or group ID (GID) of a file that is being backed up is greater than 2097151, Oracle Secure Backup substitutes the value 60002 for the UID or GID in the tar header file and returns a warning. This is because the maximum value for UID and GID, as defined by the POSIX standard (extended tar format), is 2097151. Therefore, when this backup is restored, the UID or GID for the restored file is 60002.

Syntax

obtar -c::=

obtar -c [ -f device ]
[ -H host ] [ -G ]
[ -v [ -v ]  ] [ -z ]
{ [ -C directory ] pathname... }...

Semantics

You can specify several options with obtar -c. This section describes those options that you are most likely to use. Refer to "obtar Options" to learn about additional obtar -c options.

-f device

Specifies the name of a tape device. If you do not specify -f, then obtar writes to the tape device specified by the TAPE environment variable, if it is defined.

-H host

Specifies the host on which the data to be backed up is located. If you do not specify -H, then obtar looks for the data on the local host.

-G

Writes an index of the contents of the backup image to the catalog and generates a volume label. The catalog data includes the names of all the files and directories written to the backup image. obtool uses this information to find the backup image containing the data to be restored.

When you create backup images with obtar -c, obtar does not ordinarily generate catalog files or volume identification. But you can use -G to generate them.

-v

Displays the path names of the files and directories being backed up. If you specify -v -v (or -vv), then obtar displays the path names of files and directories being backed up and their permissions, owner, size, and date of last modification.

-z

Create a labeled backup image.

-C directory

Causes obtar to change to the specified directory before backing up the subsequent files or directories. You use this option to control the path name information that is saved in the backup image.

pathname

Specifies one or more files or directories to back up. obtar issues a warning message if the contents of a file that you have specified change while a backup is taking place.

The backup image you create includes data and path name information. When you restore the data, obtar uses pathname as the location for the restored data. The obtar -x command, which you use to restore data, provides options that let you specify a different host or directory location for the restored data.

If pathname refers to data available through a mount of a local or remote file system, then obtar -c does not cross the mount point unless you specify -Xcrossmp.

You can also use the -C option to modify the pathname information that obtar records when you create the backup image.

Examples

Example B-1 Backing Up to a Volume

To create a backup image on a volume, specify a tape device name with the -f option. This example backs up the directory /doc to the volume loaded on the tape device tape0.

obtar -c -f tape0 /doc

Example B-2 Backing Up Multiple Files

You can specify multiple directories or files to back up at a time. This example backs up the file /jane/abc and the file /bob/xyz.

obtar -c -f my_tape /jane/abc /bob/xyz

Example B-3 Changing Directory Information

You can use the -C option to control the path name information that is saved in the backup image. You use -C to specify the directory in which subsequent path names are located. obtar does not save that directory as part of the path name information in the backup image.

This example backs up the directory /home/jane/current. It uses the -v option to display the path names of the data being backed up.

obtar -cv -f tape1 -C /home/jane current

current/
current/file1
current/file2

As shown in the information displayed by the -v option, the path name information that obtar records in the backup image is the content of the relative path name current. When you subsequently restore the directory, unless you specify otherwise, obtar restores it to the directory named current, relative to your current directory.

Example B-4 Changing Directory Information

This example backs up the files /test/proj3/trial7/test1 and /test/proj3/trial7/test2.

obtar -cv -f /dev/nrwst1 -C /test/proj3 trial7/test1 trial7/test2

trial7/test1
trial7/test2

The path name information that obtar records in the backup image includes the relative path names trial7/test1 and trial7/test2. When you subsequently restore the files, unless you specify otherwise, obtar restores them to the directory trial7 in your current working directory, first creating trial7 if it does not exist.

obtar -x

Purpose

Use obtar -x to extract files from a backup image. You can extract the entire contents of a backup image or only part of the backup image.

To restore data to your own directories, you do not need special rights. To restore data into directories as root, you must be either be logged in as root or specify the -R option with the obtar command.

Syntax

obtar -x::=

obtar -x [ -kpORvzZ ]
[ -f device ]...
[ -F { cur|file-number } ]
[ -H destination-host ]
[ -s,prefix,[replacement,] ] [ pathname ]...

Semantics

You can specify several options with obtar -x; this section describes those options that you are most likely to use. Refer to "obtar Options" to learn about additional obtar -x options.

pathname

Specifies the path names of files or directories to be extracted from the backup image. If you specify a directory, then obtar recursively extracts the contents of the directory. If you do not specify a path name, then obtar extracts the entire contents of the backup image.

-f device

Specifies the name of the tape device where the data is located. If you do not specify -f, then obtar reads from the tape device specified by the TAPE environment variable, if it is defined.

-F {cur|file-number}

Specifies the number of the backup image on the volume set. If you do not specify -F, then obtar extracts the backup image at the current position of the volume. If you specify cur, then obtar extracts the backup image at the volume's current position. This is the default. If you specify file-number, then obtar extracts the backup image at the specified file position.

-H destination-host

Specifies the host to which the data is restored. If you do not specify -H, then obtar restores the data to the local host.

-s,prefix,[replacement,]

Specifies where obtar should place the extracted files and directories. Use this option to extract files from a backup image and place them in a location that differs from the place from which you backed them up.

When you use -s, obtar substitutes the replacement string for prefix in the path name being restored. prefix must include the first part of the original path name. For example, if you backed up the directory /home/jane/test, and if you wanted the data restored to /home/tmp/test, then you would specify the string as follows:

-s,/home/jane,/home/tmp

If you omit the replacement string, then obtar assumes a null string, which causes obtar to remove the prefix from every pathname where it is found. The delimiter character, shown as a comma (,) in the syntax statement, can be any character that does not occur in either the prefix or the replacement string.

When you use -s, obtar displays the names of the files or directories as they are restored.

-k

Prevents obtar from overwriting any existing file that has the same name as a file in the backup image. In other words, obtar only restores files that do not exist.

-O

Causes obtar to stop after restoring the requested files. If -O is not specified, then obtar searches the entire backup image for subsequent copies of the requested files.

-R

Causes obtar to run with root access. To use -R you must be a member of a class with the perform restores as privileged user right. You are not required to use -R if you are logged in as root.

-v

Displays the path names of the files and directories being restored. If you specify -v -v (or -vv), then obtar displays the path names of files and directories being restored and their permissions, owner, size, and date of last modification.

-z

Displays the volume label of the backup image if it has one.

-Z

Prevents obtar from decompressing any data that was compressed previously with -Z. If you do not specify -Z, then obtar decompresses any data that was compressed previously with -Z.

Examples

Example B-5 Extracting Files from a Backup Image

This example extracts the contents of backup image 4, which is on the volume loaded on tape device tape1.

obtar -x -f tape1 -F 4

Example B-6 Displaying the Contents of a Backup Image

This example uses the -v option to display the contents of the backup image as it is being extracted.

obtar -x -v -f tape1 -F 4

doc/
doc/chap1
doc/chap2
test/
test/file1
test/file2

Example B-7 Displaying the Volume Label

This example uses the -z option to display the volume label of the volume being extracted.

obtar -x -z -f tape1 -F 4

Example B-8 Extracting Data to a Different Location

Use the -s option to place the extracted data in a location different from its original location. This option is particularly useful if you have backed up data and specified absolute path names. If you do not use -s, then obtar restores the data into the original directory, overwriting any existing data with that same name. This example extracts the /doc directory and places it in a directory called /tmp/doc.

obtar -x -f tape1 -s,/doc,/tmp/doc, /doc

Example B-9 Preventing obtar from Overwriting Files

This example prevents obtar from overwriting any files in the /doc directory that have the same names as files in the backup image:

obtar -x -f tape1 -k /doc

Example B-10 Restoring a Raw File-System Partition

This example restores the contents of a raw file-system partition. The partition is assumed to have been previously formatted and to be currently unmounted.

obtar -x -f tape0 /dev/rdsk/dks0d10s1

obtar -t

Purpose

Use obtar -t to list the names of files and directories contained in a backup image. You can list the entire contents of a backup image or just part of the backup image. You can catalog a backup image by specifying -Gt. obtar -t does not list or import NDMP backups.

Syntax

obtar -t::=

obtar -t [ -f device ]
[ -F { cur | file-number } ]
[ -Gvz ]
[ pathname ]...

Semantics

You can specify several options with obtar -t; this section describes those options that you are most likely to use. Refer to "obtar Options" to learn about additional obtar -t options.

-f device

Specifies the name of a tape device. If you do not specify -f, then obtar reads from the tape device specified by the TAPE environment variable, if it is defined.

-F {cur | file-number}

Specifies the number of the backup image on the volume set. If the file is on a volume different from the one currently loaded, then obtar prompts you to make any required volume changes. If you do not specify -F, then obtar reads the backup image at the current position of the volume.

If you specify cur, then obtar reads the backup image at the volume's current position. This is the default.

If you specify file-number, then obtar reads the backup image at the specified file position.

-v

Displays additional information about the contents of the backup image. The output is similar to that of the UNIX ls -l command. The additional information includes file and directory permissions, owner, size, and date of last modification.

-z

Displays the volume label of the backup image.

pathname

Specifies one or more path names of files or directories you want listed. If you specify a directory, then obtar recursively lists the contents of the directory. If you do not specify any path name arguments, then obtar lists the entire contents of the backup image at the volume's current location or at the location you specify with the -F option.

Examples

Example B-11 Displaying the Contents of a Backup Image

This example displays the contents of the backup image located at the current position of the volume loaded on tape device tape1.

# obtar -t -f tape1

project/
project/file1
project/file2
project/file3

Example B-12 Displaying the Contents of a Backup Image on a Volume Set

To display the contents of a particular backup image on a volume set, use the -F option. This example displays the contents of backup image 4.

# obtar -t -f tape1 -F 4

doc/
doc/chap1
doc/chap2
test/
test/file1
test/file2

Example B-13 Displaying Additional Information About a Backup Image

To display additional information about a backup image, use the -v option. This example uses the -v option to display additional information about backup image 4.

# obtar -t -v -f tape1 -F 4

drwxrwxr-x jane/rd       0 Feb 24 16:53 2000 doc/
-rw-r--r-- jane/rd     225 Feb 24 15:17 2000 doc/chap1
-rwxrwxr-x jane/rd     779 Feb 24 15:17 2000 doc/chap2
drwxrwxr-x jane/rd       0 Feb 24 16:55 2000 test/
-rwxrwxr-x jane/rd     779 Feb 24 16:54 2000 test/file1
-rw-r--r-- jane/rd     225 Feb 24 16:54 2000 test/file2

Example B-14 Displaying Information About a File in an Image

To display information about a particular file or directory that is contained in the backup image, include the file or directory name as the last argument on the command line. This example displays information about the directory test, which is contained in backup image 4.

# obtar -t -f tape1 -F 4 test

test/
test/file1
test/file2

Example B-15 Displaying Information About Multiple Directories

You can specify multiple path names from the backup image. This example displays information about the directories test and doc. obtar lists the directories in the order they appear in the backup image.

# obtar -t -f tape1 -F 4 test doc

doc/
doc/chap1
doc/chap2
test/
test/file1
test/file2

Example B-16 Cataloging a File-System Backup Image

Use the -G option to catalog the contents of a backup image. This example catalogs backup image 1 on the volume loaded into tape drive tape1 (only partial output is shown). In this example, the image contains a file-system backup. You can catalog only one backup image at a time.

# obtar -f tape1 -tG -F 1

Volume label:
    Volume tag:         DEV100
    Volume ID:          VOL000001
    Volume sequence:    1
    Volume set owner:   root
    Volume set created: Tue Nov 22 15:57:36 2012

Archive label:
    File number:        1
    File section:       1
    Owner:              root
    Client host:        osbsvr2
    Backup level:       0
    S/w compression:    no
    Archive created:    Tue Nov 22 15:57:36 2012

/home/someuser/
/home/someuser/.ICEauthority
/home/someuser/.Xauthority
/home/someuser/.aliases
/home/someuser/.bash_history
/home/someuser/.bash_logout
/home/someuser/.bash_profile
/home/someuser/.bashrc
.
.
.

Example B-17 Cataloging an RMAN Backup Image

This example also catalogs backup image 1 on the volume loaded into tape drive tape1. In this example, the image contains an RMA backup of archived redo log files.

# obtar -f tape1 -tG -F 1

Volume label:
    Volume tag:         ADE202
    Volume ID:          RMAN-DEFAULT-000002
    Volume sequence:    1
    Volume set owner:   root
    Volume set created: Mon Feb 13 10:36:13 2006
    Media family:       RMAN-DEFAULT
    Volume set expires: never; content manages reuse
 
Archive label:
    File number:        1
    File section:       1
    Owner:              root
    Client host:        osbsvr1
    Backup level:       0
    S/w compression:    no
    Archive created:    Mon Feb 13 10:36:13 2006
    Backup piece name:  05hba0cd_1_1
    Backup db name:     ob
    Backup db id:       1585728012
    Backup copy number: non-multiplexed backup
    Backup content:     archivelog

obtar -zz

Purpose

Use obtar -zz to display all Oracle Secure Backup labels on a volume.

Syntax

obtar -zz::=

obtar -zz [ -f device ]

Semantics

You can specify several options with obtar -zz; this section describes the option that you are most likely to use. Refer to "obtar Options" to learn about additional obtar -zz options.

-f device: Specifies the name of a backup image file or tape device. If you omit the -f option, then obtar reads from the tape device specified by the TAPE environment variable, if it is defined.

Example

Example B-18 Displaying the Labels of All Backup Images on a Volume

As shown in Example B-18, you can use -zz to display the labels of all backup images on a volume.

obtar -zzf tape0

Seq  Volume    Volume    Backup Image    Client    Backup    Backup Image Create
#    ID        Tag       File Sect       Host      Level     Date & Time
1    VOL000003             1   1         campy       0       05/01/00 14:08:23
1    VOL000003             2   1         phred       0       05/01/00 15:37:00
1    VOL000003             3   1         mehitibel   0       05/01/00 15:38:08

obtar Options

The rows in Table B-2 lists obtar options alphabetically. The columns indicate the obtar modes in which the options can be specified.

Table B-2 obtar Options

Option	-c	-t	-x	-zz
-A	x
-b	x	x	x
-B		x	x
-C	x
-e	x^Foot 1	x	x
-E	x^Foot 2
-f	x	x	x	x
-F	x	x	x
-G	x	x
-h	x
-H	x		x
-J	x	x	x	x
-k			x
-K	x		x
-l	x		x
-L	x
-m			x
-M	x
-O			x
-P	x
-q		x	x
-R	x	x	x	x
-s			x
-u			x
-U	x
-v	x	x	x
-V
-w	x		x
-Xallowdiffspldev			x
-Xcatalog
-Xchkmnttab	x		x
-Xcleara	x
-Xcrossmp	x		x
-Xdepth	x	x	x
-Xfamily	x
-Xhighlatency	x
-Xhome	x		x
-Xincrrestore			x
-Xinstance
-Xkv	x
-Xmarkerfiles	x
-Xnice	x	x	x	x
-Xno_mod_chk	x
-Xnochaselinks	x
-Xnostat	x
-Xow	x
-Xupdtu	x
-Xuq	x
-Xuse_ctime	x
-Xverifyarchive	x
-Xww	x
-y	x
-Z	x		x

^Footnote 1

when -G is also specified

^Footnote 2

when -G is also specified

-A

Does not save Access Control Lists (ACLs), Context Dependent Files (CDFs), and other extended file-system attributes for files backed up on Hewlett-Packard platforms (HP-UX operating system). By default, obtar saves all file-system attributes for each file. When you restore these files on Hewlett-Packard platforms, the extended attributes are also restored.

When you restore these files on other platforms, obtar ignores the ACL information.

On Windows, Linux, and UNIX platforms, the -A flag causes obtar to save only the primary data stream associated with each file, excluding the extended attributes and ACLs.

See also:

"Oracle Secure Backup Support for Extended Attributes and Access Control Lists" for more information on performing backup and recovery with extended attributes and access control lists

-b blocking-factor

Writes data in block sizes of blocking-factor multiplied by 512 bytes. By default, obtar uses the blocking factor specified by the blockingfactor media policy. When you restore files, obtar automatically determines the block size that was used when backing up the data.

-B

Performs multiple reads to fill a block. If you are using obtar with UNIX pipes or sockets, then the UNIX read function can return partial blocks of data even if more data is coming.

For example, suppose you want to restore data from a tape device that is attached to a host where Oracle Secure Backup is not installed. The following command restores the /doc directory from a tape device attached to the host named logan:

rsh logan cat /dev/nrst0 | obtar -x -B -f - /doc

If you specify a remote tape device with the -f option, then you are not required to use -B because the obtar network protocol guarantees reading and writing full blocks.

-C directory

Changes the directory structure associated with the files being backed up. With this option, obtar changes its working directory to directory and backs up files relative to it. obtar uses directory as its current directory until the next -C option on the command line. When you restore the files, they are restored relative to directory.

-e volume-id

Uses volume-id in the volume label for this backup image (when backing up) or looking for volume-id in the volume label (when restoring). A volume ID contains up to 31 characters, in any combination of alphabetic and numeric characters, although the last 6 characters must be numeric. If you do not specify a volume ID when backing up, then obtar uses the volume ID in the volume-sequence file in the administrative directory (the default) or the volume ID file specified with the -E option.

Typically, you use -e to verify that you are restoring the correct volume when running obtar -x or obtar -t from a script. obtar tries to match the volume ID with the volume ID in the label and exits if it does not find a match. If the tape drive from which you are indexing or restoring data is contained within a tape library, then supplying -e on the command line directs obtar to attempt to load that volume into the tape drive before beginning the operation.

-E volume-id-file

Uses the volume ID from volume-id-file in the volume label. obtar looks for volume-id-file in the administrative directory on the administrative server. If you do not specify this option, then obtar uses the volume ID from volume-sequence, the default volume ID file.

-f device

Specifies the name of the tape device on which you want the backup image created. The device argument to -f is the name that you have assigned to a tape drive in an administrative domain.

If you do not specify the -f option, then Oracle Secure Backup uses the tape device specified by the TAPE environment variable, if it is defined.

When you are backing up a large amount of data, obtar might be required to continue a backup image from one volume to the next. If the tape drive resides in a tape library, then obtar automatically unloads the current volume and searches the inventory of the tape library for another eligible volume on which to continue the backup. The way that you install and configure obtar indicates whether it considers a tape device to reside inside a tape library.

If you are using a standalone tape drive, and if data still must be written at the end of a volume, then obtar rewinds the tape and unloads it. obtar displays a message like the following on the operator host, where vol-id refers to the next volume in the volume set:

End of tape has been reached. Please wait while I rewind and unload the tape. The
Volume ID of the next tape to be written is vol-id.
The tape has been unloaded.

Please insert new tape on device
and press <return> when ready:

The backup continues onto the next volume.

-F {cur | end | file-number}

Writes or reads a backup image at the indicated position in a volume set, instead of the current volume position (default). Use this option only when writing to or reading from a tape device. obtar positions the tape to the requested file in the volume set. If the file is on a volume that is not loaded, then obtar prompts you to load the necessary volume.

If you specify the position as cur, then obtar writes or reads the backup image at the current volume position.

If you specify end, then obtar writes the backup image immediately after the last existing backup image in the volume set.

If you specify file-number, then obtar writes the backup image at the specified file position. obtar numbers each backup image on a volume set sequentially, beginning with 1.

Note:

When obtar creates a backup image at a specified volume position, the backup image becomes the last backup image, even if the volume previously contained additional backup images. For example, if you write a backup image at position 6 on a volume containing 11 backup images, then you effectively erase backup images 7 through 11. With obtar -t and obtar -x, you can use the -q option instead of this option.

-G

Writes an index of the backup image contents to the catalog and generates a volume label. The contents can include file-system backups or Recovery Manager (RMAN) backups. obtool uses this information to find the backup image containing the data to be restored.

-h

When the data to be backed up includes symbolic links, obtar ordinarily backs up only the link text, not the data to which the link points. You can use the -h option to cause obtar to back up the data, not just the link text.

If you include an explicit link path name when using obtar -c, then obtar backs up the data specified by that link whether you have used the -h option or not. If you do not want obtar to follow explicitly mentioned links, then you can do so by specifying -Xnochaselinks.

-H host

Backs up data from or restores data to host instead of from the local host (default).

-J

Directs obtar to produce debugging output as it runs.

-k

Restores only the files that do not exist. That is, obtar does not overwrite any existing files with the version from the backup image. By default, obtar overwrites any existing files.

-K mask

Specify device driver debug options. mask is the bitwise inclusive or of the following values shown in Table B-3.

Table B-3 mask Values

Value	Meaning
800	Turn on debug modes before open
400	Allow only one write at BOT
200	Inject write error
100	Debug kernel driver
080	Enable time-outs
040	Disable time-outs
020	Enable debugging at EOM
010	Generate early EOT
008	Trace DMA activity
004	Trace miscellaneous info
002	Trace errors
001	Trace driver calls

Note:

This option can lead to voluminous output and should normally be used only when directed by Oracle Support Services.

-l

Forces obtar not to cross file-system mount points when backing up or restoring.

By default, obtar does not cross mount points unless you explicitly include mount point statements in a backup description file. If you specify -l, then obtar ignores these explicit override settings and does not cross mount points.

Note that if you also specify -Xchkmnttab, then specifying -l causes obtar to consult the mount table (/etc/mnttab) to avoid crossing remote mount points.

When backing up or restoring an NT File System (NTFS) partition under Windows 2000, name surrogate reparse points (for example, directory junctions) are treated as mount points.

If you use this option with the -v option, then obtar writes the names of any files it skips to standard error.

-L {full | incr | exincr | offsite | n | date-time}

Uses the specified backup level instead of a full backup (default).

full specifies a full backup, which saves all data that is specified in the obtar -c command.

incr specifies an incremental backup, which saves only the data that was modified since the last backup.

exincr specifies an extended incremental, which saves only the data that was modified since the last full backup.

offsite generates an on-demand backup that does not affect the subsequent scheduling of full and incremental backups.

You can also specify a numeric backup level, n, which can range from 0 to 9 and saves only the data that was modified since the last backup at a lower level. Backup level 0 is identical to full, and level 1 is identical to exincr.

If you use a date-time argument, then obtar saves only the data that was modified since that time. Note that using a date-time argument does not create a true incremental backup because it cannot be used as a reference point for later incremental backups. The date-time argument must be in the form appropriate to the locale in which you run obtar. For the U.S., specify date-time in the following format:

mm/dd[/yy] [hh[:mm[:ss]]]

If you supply hh, hh:mm, or hh:mm:ss as part of date-time, then you must enclose date-time in quotes. If you do not supply the year (/yy), then obtar uses the preceding 12 months. If you supply hh:mm but not ss, then obtar uses hh:mm:59.

-m

Uses the current time as the last time modified timestamp instead of the time that is saved with the backup image (default).

In the following example, the timestamp for all directories and files in the /old directory is changed to the current date and time:

obtar -x -m -f tape0 /old

-M parameter:value

You can use -M to turn hardware compression on or off for any tape device that supports hardware compression. obtar turns hardware compression on by default. To set hardware compression, specify on to turn hardware compression on, and specify off to turn hardware compression off:

-M compress:{on|off}

If you turn on hardware compression, then the tape device automatically decompresses data when you restore it. You should not use hardware compression at the same time as the -Z option.

-O

Ends a restore operation after first occurrence of files being restored. Normally, obtar -x scans an entire backup image looking for multiple copies of each file to be restored. If you specify -O, then the restore stops after each file has been restored once.

-P

A sparse file is a file with areas that have never be written to. Ordinarily, obtar does not usually perform any special handling of sparse files. If you specify the -P option when you create a backup image with obtar -c, then obtar compacts any sparse files in the backup image. When you subsequently restore the backup image, obtar restores the sparse files to their original format.

Note:

This option does not apply to sparse files under Windows 2000, which are always backed up and restored in sparse form.

-q position-string

If you are using a tape device that supports direct-to-block positioning, then you can use the -q option to rapidly locate particular data on a volume. The argument to -q is a position-string that you obtain from the ls --backup --position command in obtool. When you use -q, obtar positions the volume directly to the location you specify.

For example, you can use the ls command in obtool to identify the position of the file /home/gms/output/test001:

obtool ls --backup --position /home/gms/output/test001

test001
Backup Date & Time ID  Volume ID Volume Tag File Sect  Level Position
2006/01/11.10:16:28 3  VOL000106   00000110   11    0    000045020008

After obtaining the position data, you can specify the -q option with obtar -t as shown in the following example:

obtar -t -f tape1 -q 000045020008

-R

Runs obtar with root access. To use -R you must be a member of a class with the perform file system restores as privileged user or perform file system backups as privileged user right. You are not required to specify -R if you are logged in as root.

-s,prefix,[replacement,]

Substitutes replacement for each occurrence of prefix in all path names that are being restored. prefix must include the first part of the original path name. If you omit replacement, then obtar removes all occurrences of prefix in all path names being restored. If the character does not occur in either the prefix or the replacement string, then you can use another delimiter character instead of a comma (,). You can use this option to extract files from a backup image and place them in a location different from where they were backed up.

-u

When restoring files, obtar overwrites existing files unless explicitly told not to. On systems that support file locking, this replacement of existing files occurs even for files that are currently in use. Specify -u on the obtar command line to avoid overwriting files that are currently in use.

-U

Updates backup dates file in the administrative directory. This option overrides the setting of the autohistory operations policy.

-v

Writes verbose information about files to standard output or standard error.

When used with obtar -c, this option writes the names of the files being backed up and the volume label (if one was created) to standard error.

When used with obtar -t, this option writes additional information about the files, which is similar to the output of the ls -l command, instead of writing just the filenames (default) to standard output.

When used with obtar -x, this option writes the names of the files being restored to standard output. If you specify -vv, then obtar writes verbose information about files, which is similar to the output of the ls -l command, to standard error (obtar -c), or standard output (obtar -x).

Note:

The user ID (UID) or group ID (GID) reported by the -v option might not match the actual UID or GID for a file. The maximum values for UID and GID are defined by the POSIX standard (extended tar format). During a backup operation, if Oracle Secure Backup encounters a file whose UID or GID exceeds the maximum (2097151) that fits in a tar header, then it substitutes 60002 as the UID or GID and returns a warning. The exit status of the backup reflects the presence of such warnings.

-V

Prints the version of obtar and exits.

-w

Directs obtar to check for and honor advisory file locks before backing up or restoring a file. If a lock is set, then obtar displays a warning message and skips the file.

-Xallowdiffspldev

By default, you can restore a raw partition only to a block device that has the same major or minor number as the block device to which the partition was backed up. To restore a raw partition to a block device whose major or minor numbers are different from number of the block device to which the partition was backed up, use the -Xallowdiffspldev option.

Note:

The Xallowdiffspldev option is only available starting with Oracle Secure Backup 10.3.0.2.0.

-Xcatalog

Allows cataloging of a single instance from a disk pool or cloud container device. Use this option with the -Xinstance option to specify the instance UUID to be imported.

-Xchkmnttab

Causes obtar to consult the local mount table (/etc/mnttab) before performing stat(2) operations and to skip directories known to be remote mount points. Local mount points are not skipped. This option applies to Linux and UNIX only.

The -Xchkmnttab option can avoid hangs caused by remote hosts that are down or not responding. The -Xchkmnttab option is overridden by -Xcrossmp.