obtar Options

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

^Footnote 1 when -G or -z is also specified

^Footnote 2 when -G or -z 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, if you pipe a remote dd(1) command to obtar, use this option so that obtar reads exactly the number of bytes to fill each block.

-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 library, then supplying -e on the command line directs obtar to attempt to load that volume into the 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 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 device specified by the TAPE environment variable, if it is defined.

When you are backing up a large amount of data, obtar may need to continue a backup image from one volume to the next. If the tape drive resides in a library, then obtar automatically unloads the current volume and searches the inventory of the 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 device to reside inside a library.

If you are using a standalone tape drive, and if data still needs to 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 (the host on which you execute the obtar command), 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.

obtar then prompts you to load the next volume and press the Return key when you are ready:

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, 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 RMAN backups. obtool uses this information to find the backup image containing the data to be restored.

-h

Backs up the data pointed to by symbolic link files rather than the symbolic link files themselves (default). If you use obtar -g and specify symbolic links as inclusion statements (see "Inclusion Statement") in the backup description file, then obtar always follows the links. If you also specify -Xnochaselinks, then links are never followed, regardless of where they appear.

-H host

Backs up data from or restores data to host instead of from the local host (default). If you are using obtar -g, then you can specify the host in the backup description file instead of using this option. If your backup description file already has a host, then you cannot use this option.

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

Table 4-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 (see "Mount Point Statement"). 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 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 backup description file.

incr specifies and 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, 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).

-M parameter:value

Sets hardware compression and format for certain tape devices.

When you are using an Exabyte 8500, 8500c, or 8505 tape device, you can use -M to create backup images that can also be used with Exabyte 8200 tape devices. To set the format, specify the following:

-M format:{8200|8500}

Specify 8200 to change to 8200 format, and specify 8500 to change to 8500 format. If you do not specify either, then obtar uses 8500 format.

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

-M compress:{on|off}

Specify on to turn hardware compression on, and specify off to turn hardware compression off.

If you turn on hardware compression, then the device automatically uncompresses data when you restore it. You should not use hardware compression at the same time as the -Z option. Also, if you use the WangDAT 2600 device, then changing the hardware compression setting takes about 55 seconds because the drive automatically reformats the tape.

-O

Terminates 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

Restores the permissions that were backed up with the files and directories. If you do not specify -p, then the current UNIX umask determines the permissions of restored files.

-P

Condenses any sparse files when backing up. A sparse file is a file with holes—areas in the file that have never be written to. When you restore these files, obtar restores the sparse files to their original format.

-q position-string

Positions the volume to position-string before restoring the backup image or listing its table of contents. The string must specify the position of a file within the backup image on the volume. You can use the obtool command to display the position-string for a file.

-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 do not need 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 leftmost 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.

-S { a | G | U | z }

Suppresses the action of options that are implicitly part of obtar -g. The G argument suppresses the generation of index data; the U argument suppresses the updating of the backup dates files; and the z argument suppresses the writing of a volume label. The a argument suppresses all three (G, U, z).

-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 and obtar -g, 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 and obtar -g), or standard output (obtar -x).

-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. Note that you can specify the -Xchkmnttab option in the backupoptions operations policy. The -Xchkmnttab option is overridden by -Xcrossmp.

-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, or whether mount point statements are included in the BDF (see "Mount Point Statement"). 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 NDMP restore for 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 will not back up this directory or any of its subdirectories.

-Xndmptype:type

Specifies the type of NDMP backup to be performed. type is one of dump, tar, gtar, or image.

-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 in a backup description file or 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.

-Xpre20

Restores or lists files from pre-2.0 backup images. On backup images created by versions of obtar prior to 2.0, block-special and character-special files were saved with a nonzero size (st_size), which is incorrect.

-Xtag[:tag]

Specifies tag as the volume tag (barcode) to be written to the volume label. This option is not required if Oracle Secure Backup is already aware of the volume's tag or the volume resides in a library equipped with a barcode reader and the volume has a readable barcode attached.

-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 execute 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 servers only.

-Xwritev2ndmppos

Writes a version 2 NDMP position file. Such files are compatible with all Oracle Secure Backup 2.5 and 2.6 systems.

-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. This option is useful when running obtar from a shell script.

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