Skip Headers

Oracle® Secure Backup Reference Release 10.2 Part Number E05410-02 |
Home | Book List | Contents | Index | Contact Us

Previous | Next
| View PDF

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

- obtar -x

- obtar -t

- obtar -zz

- obtar Options

- Optimizing Your Use of obtar

## 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 as long as no more than one of the options requires an argument. If one of the options 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 F-1 explains the basic obtar modes. The description of each mode includes the most common options. "obtar Options" describes additional options.

Table F-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.

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

Syntax

obtar -c::=

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

Semantics

You can specify a number of 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 [-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 as well as 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

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

Example F-1 Backing Up to a Volume

    obtar -c -f tape0 /doc

You can specify more than one directory or file to back up at a time. Example F-2 backs up the file /jane/abc and the file /bob/xyz.

Example F-2 Backing Up Multiple Files

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

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.

Example F-3 backs up the directory /home/jane/current. It uses the `-v` option to display the path names of the data being backed up.

Example F-3 Changing Directory Information

    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 F-4 backs up the files /test/proj3/trial7/test1 and /test/proj3/trial7/test2.

Example F-4 Changing Directory Information

    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 a number of 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 will be 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 already 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 [-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 F-5 extracts the contents of backup image 4, which is on the volume loaded on tape device tape1.

Example F-5 Extracting Files from a Backup Image

    obtar -x -f tape1 -F 4

Example F-6 uses the `-v` option to display the contents of the backup image as it is being extracted.

Example F-6 Displaying the Contents of a Backup Image

    obtar -x -v -f tape1 -F 4

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

Example F-7 uses the `-z` option to display the volume label of the volume being extracted.

Example F-7 Displaying the Volume Label

    obtar -x -z -f tape1 -F 4

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. Example F-8 extracts the /doc directory and places it in a directory called /tmp/doc.

Example F-8 Extracting Data to a Different Location

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

Example F-9 prevents obtar from overwriting any files in the /doc directory that have the same names as files in the backup image:

Example F-9 Preventing obtar from Overwriting Files

    obtar -x -f tape1 -k /doc

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

Example F-10 Restoring a Raw File System Partition

    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 Network Data Management Protocol (NDMP) backups.

Syntax

obtar -t::=

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

Semantics

You can specify a number of 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 F-11 displays the contents of the backup image located at the current position of the volume loaded on tape device tape1.

Example F-11 Displaying the Contents of a Backup Image

    # obtar -t -f tape1

    project/
    project/file1
    project/file2
    project/file3

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

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

    # obtar -t -f tape1 -F 4

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

To display additional information about a backup image, use the `-v` option. Example F-13 uses the `-v` option to display additional information about backup image 4.

Example F-13 Displaying Additional Information About a Backup Image

    # 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

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. Example F-14 displays information about the directory test, which is contained in backup image 4.

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

    # obtar -t -f tape1 -F 4 test

    test/
    test/file1
    test/file2

You can specify more than one path name from the backup image. Example F-15 displays information about the directories test and doc. obtar lists the directories in the order they appear in the backup image.

Example F-15 Displaying Information About Multiple Directories

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

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

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

Example F-16 Cataloging a File System Backup Image

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

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

    /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 F-17 also catalogs backup image 1 on the volume loaded into tape drive tape1. In this example, the image contains a Recovery Manager (RMAN) backup of archived redo logs.

Example F-17 Cataloging an RMAN Backup Image

    # 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:        stadv07
        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 a number of 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

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

Example F-18 Displaying 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 F-2 lists obtar options alphabetically. The columns indicate the obtar modes in which the options can be specified.

Table F-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 |
-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 or not 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 new 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 new 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 or not you have used the `-h` option. 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 already 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 F-3.

  Table F-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` can be used to generate 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 the same as full, and level 1 is the same as `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 restores as privileged user or perform 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 will overwrite 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 will fit 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.

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

-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, this data is written to the index file and subsequently imported 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 will fail 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. This means that 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 already 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.

## Optimizing Your Use of obtar

This section describes ways you can optimize your use of obtar, and provides information about some of the 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 will create 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 will encounter an early end-of-file condition after it extracts the first section of the backup image. At this point, you will 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 will not be overwritten as you continue the extraction.

2. Load the next volume and continue the extraction. The second file fragment will be 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 or character special file when backing up a tree, it usually writes only the special file name and attributes to the backup image. If a block or character special file is mentioned at the top level of the backup tree, however, either explicitly or by means of a wildcard, then obtar will back up the file name, attributes, and contents.

For example, the following command will create a backup image consisting of all the special file names in the /dev directory, but will neither open nor read any special file:

    obtar -cvf tape0 /dev

On the other hand, the following command will cause 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 other than Linux or UNIX data, for example, a disk partition containing a database.

Because obtar has no idea what 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.

In order to restore a raw file system or other block or character special file, the raw file system must have been previously formatted using mkfs, mkvol, or a similar tool, and the special file referring to the raw file system must already exist. Otherwise, the data is restored as a normal file.

Caution:

You should 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.

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