Go to main content
13/17

# 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

- Optimizing Your Use of obtar

- obtar -c

- obtar -x

- obtar -t

- obtar -zz

- obtar Options

## 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

- Backing Up and Restoring Raw File Systems

- Changing Criteria for Incremental Backups

- Backing Up Across Mount Points

### 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:

1. Move the first file fragment to a location that is not overwritten as you continue the extraction.

2. Load the next volume and continue the extraction. The second file fragment is extracted.

3. 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

4. Delete the file fragments.

### Backing Up and Restoring Raw File Systems

When `obtar` encounters a block special file when backing up a tree, it usually writes only the special file name and attributes to the backup image. If a block 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.

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 or other block special file, 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.

Caution:

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 Using the Block Device Interface

You can use obtool to back up raw partitions using the block device interface. 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:

1. 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
       }

2. 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 Using the Block Device Interface

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

To restore raw partitions:

1. 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

2. 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.

See Also:

"backupoptions"

## 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.

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/tes`t, 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 2008

    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 2008

    /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 | xFoot 1 | x | x |
-E | xFoot 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 |
-Xchkmnttab | x |  | x |
-Xcleara | x |  |  |
-Xcrossmp | x |  | x |
-Xdepth | x | x | x |
-Xfamily | x |  |  |
-Xhighlatency | x |  |  |
-Xhome | x |  | x |
-Xincrrestore |  |  | x |
-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 |  |  |
-Xwq | 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 platforms, the `-A` flag causes `obtar` to save only the primary data stream associated with each file.

-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 trims 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.
-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.

  See Also:

  "backupoptions" for instructions on specifying the `-Xchkmnttab` option in the `backupoptions` operations policy
-Xcleara

  Clears the archive file attribute bit for each file that is successfully backed up. In the absence of this option, `obtar` leaves the archive file bits unmodified. Windows only.

-Xcrossmp

  Directs `obtar` to cross all mount points regardless of whether the -l or -Xchkmnttab options are specified. By default, `obtar` does not cross mount points.

  Note that you can specify the `-Xcrossmp` option in the backupoptions operations policy.

-Xdepth:levs

  Specifies the maximum number of index levels to display.

-Xfamily[:family]

  Specifies that the volume being labeled belongs to media family `family`.

-Xhighlatency

  Causes `obtar` to fetch data pointed to by a reparse point. Normally, when confronted with a high latency reparse point, `obtar` backs up the reparse point, but not the underlying data. Windows only.

-Xhome:dir

  Sets the home directory on the client host to `dir` before starting a backup.

-Xincrrestore

  Performs an incremental Network Data Management Protocol (NDMP) restore for Network Attached Storage (NAS) devices.

-Xkv:time_spec

  Specifies the length of time a volume should be retained. `time_spec` is `disabled` (no retention time), `forever`, or `n tu`, where `tu` is one of `secs` (or seconds), `mins` (minutes), `hrs` (hours), `days`, `wks` (weeks), `mos` (months), or `yrs` (years). This option is effective only when writing to the first file of a volume.

-Xmarkerfiles

  Directs `obtar` to honor index marker files encountered during a backup. Currently, there is a single index marker file defined: `.ob_no_backup`. If a file with this name appears in a directory, and if you specify `-Xmarkerfiles`, then `obtar` does not back up this directory or any of its subdirectories.

-Xnice:val

  Directs `obtar` to set the `nice(1)` value for the backup or restore process to `val`. This value is propagated to any local and remote subprocesses spawned by `obtar` to perform the requested operation.

  On Windows, the specified val is mapped to a Windows process priority value according to the following rules:

  - If val >= -20 and val <= -6, then the value is translated into `ABOVE_NORMAL_PRIORITY_CLASS`.

  - If val >= -5 and val <= 4 it is translated into `NORMAL_PRIORITY_CLASS`.

  - If val >= 5 and val <= 19 it is translated into `BELOW_NORMAL_PRIORITY_CLASS`.

  - If the value does not fall in the preceding ranges, then `obtar` issues a warning and ignores the value.

-Xno_mod_chk

  Omits a modification check when backing up a file. Normally, after `obtar` has backed up a file, it checks whether the file was modified while it was being backed up. If the file was modified, then `obtar` prints a warning message. Setting this option can improve performance.

-Xnochaselinks

  Avoids following links anywhere, even if they are explicitly mentioned on the command line.

-Xnostat

  Does not include file stat data (ownership, permissions, size) in index file. By default, Oracle Secure Backup writes this data to the index file and subsequently imports it into the catalog.

-Xow

  Disregards any expiration date in the volume label. If you try to overwrite a volume that has not yet expired, then the operation fails unless you specify `-Xow`.

-Xupdtu

  Does not reset a file's access time after backing it up. After `obtar` has backed up a file, it normally resets the file's access time (`atime`) back to what it was before the backup started. The act of backing of a file does not change the original `atime`. If you are not concerned with backups changing files' `atimes`, then specifying this option results in a slight increase in backup performance.

-Xuq:n

  Specifies the size of the `utime` helper queue. When backing up data, `obtar` uses a helper process to run `utime(2)` calls to reset access times on files being backed up. This parameter controls the size of the input queue for the `utime` helper. Linux and UNIX only.

-Xuse_ctime

  Directs `obtar`, when performing an incremental backup, to use the `ctimes` (inode change times) rather than `mtimes` (modified times) for files as the criteria for being included in the backup. Use of this option implies `-Xupdtu`.

-Xverifyarchive

  Causes `obtar`, on completing a backup section, to backspace the tape to the beginning of the section and read the contents.

-Xwq:n

  Specifies the maximum number of unfinished remote writes. This parameter controls the number of writes in this queue. Linux and UNIX media server hosts only.

-Xww:time_spec

  Specifies the write window expiration time for a volume. `time_spec` is specified as for the `-Xkv` option. The given time specification is added to the time at which the volume is created to determine a time after which further writes to the volume are disallowed. This option is effective only when writing to the first file of a volume.

-y status-file

  Writes status information about the backup session to `status-file`. You can retain these statistics in the media server observiced log file by setting the `retainbackupmetrics` policy.

  See Also:

  "retainbackupmetrics"
-Z

  Compresses data (when backing up) or keeps data compressed (when restoring). When you use `-Z` to create a backup image, `obtar` compresses files using the same algorithm as the UNIX `compress(1)` utility before writing them to the backup image. If the files are compressed or would not shrink if compressed, then `obtar` does not compress them. When you restore files that have been compressed, `obtar` automatically decompresses them unless you specify `-Z` to suppress decompression.

  Note:

  It is almost always preferable to rely on the tape drive's hardware compression capability, if it is available.