B obtar
The primary user interfaces for file-system backup and restore operations are the Oracle Secure Backup Web tool and obtool. The underlying engine that Oracle Secure Backup uses to back up and restore data is obtar
. You can use the obtar
command-line interface directly, although this practice is recommended only for advanced users.
This appendix contains these sections:
obtar Overview
obtar is a descendent of the original Berkeley UNIX tar(1)
command. The obtar command-line interface conforms to the POSIX 1003.2 standards for UNIX command lines as follows:
-
Options are single letters preceded with a dash, as in
-c
. -
If an option requires an argument, then it follows the option and can be separated from the option with a space, as in
‐c
argument
. -
Multiple options can be combined after a single dash if no multiple options require an argument. If only one option requires an argument, then this option must appear last in the group. For example, if
-c
takes an argument, then you might specify‐vPZc
argument
.
Table B-1 explains the basic obtar
modes. The description of each mode includes the most common options. "obtar Options" describes additional options.
Table B-1 obtar Modes
Option | Description |
---|---|
Creates a one-time backup image of the directories and files specified on the command line. |
|
Restores directories and files. |
|
Lists the contents for a backup image. |
|
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
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:
Backing Up and Restoring Raw File Systems
When obtar
encounters a special file while backing up a tree, it usually writes only the special file name and attributes to the backup image. If a special file is mentioned at the top level of the backup tree, however, either explicitly or with a wildcard, then obtar
backs up the file name, attributes, and contents. n this section, special files includes both block special files and character special files.
Note:
Oracle Secure Backup does not support the backup or restore of the contents of character special files.
For example, the following command creates a backup image consisting of all the special file names in the /dev
directory, but neither opens nor reads any special file:
obtar -cvf tape0 /dev
On the other hand, the following command causes obtar
to open /dev/sd0a
, /dev/sd13a
, /dev/sd13b
, and so on and write the entire contents of the underlying raw file systems to the backup image:
obtar -cvf tape0 /dev/sd0a /dev/sd13*
Because this form of access bypasses the native Linux or UNIX file system, you can use it to back up raw file systems that contain data other than Linux or UNIX data, for example, a disk partition containing a database.
Because obtar
has no idea which blocks are used or unused on the raw file system, the entire file system is always saved. This is different from a backup using the vendor-supplied Linux or UNIX file system, which saves only blocks in use.
When restoring data to a raw file system, the size of the file system to which you are restoring must be at least the size of the file system that was backed up. When restoring a raw file system, all data currently on the file system is lost. It is totally overwritten by the data from the backup image.
To restore a raw file system, the raw file system must have been formatted using mkfs
, mkvol
, or a similar tool, and the special file referring to the raw file system must exist. Otherwise, the data is restored as a normal file.
Note:
Never back up or restore a mounted file system. If a file system is mounted, then activity by other processes might change the file system during the backup or restore, causing it to be internally inconsistent.
Backing Up Raw Partitions
You can use obtool to back up raw partitions. The raw file system must not be mounted during the backup. You can back up the block device file by including the path of the device file in a dataset.
To back up raw partitions:
-
Create a dataset for the raw partition.
For example, you can create a dataset named
rawpart.ds
as follows:include host brhost2 { include path /dev/sda3 }
-
Back up the partition.
The following obtool command makes a backup using the dataset created in the previous step:
ob> backup -D rawpart.ds --restriction lib1 --go
Restoring Raw Partitions
You can use obtool to restore raw partitions. The raw file system must not be mounted during the restore operation.
To restore raw partitions:
-
Use obtool to set the host to which you want to restore:
For example, run the
cd
command as follows to set the host tobrhost2
:ob> cd --host brhost2
-
Restore the partition.
The following obtool command restores partition
/dev/sda3
:ob> restore --select latest /dev/sda3 –-go
Changing Criteria for Incremental Backups
When obtar
decides if a file is to be included in an incremental backup, it usually uses the mtime
for the file, which is the time at which the contents of the file were last modified. If a file was added to a directory by using mv
or cp -p
, then it might not get backed up because its modified time is not changed from those of the original copy of the file. You can get around this problem by telling obtar
to use ctime
, which is the status change time, rather than mtime
as the criterion for inclusion in an incremental backup. The status change time of a file is the time at which a file's inode was last modified.
Using ctime
results in the selection of all files that would have been selected using mtime
plus those that have been moved or copied into the directory. Specify this option by specifying -Xuse_ctime
on the command line. For a scheduled backup, you can include -Xuse_ctime
in the backupoptions
policy.
There is a drawback to using -Xuse_ctime
. When using the mtime
criterion, obtar
resets the atime of each file after it has been backed up. atime is the last accessed time. The act of backing up a file does not change the atime
of the file. If you are using ctime
as the selection criterion, then obtar
cannot reset the time last accessed because it would reset the file's change time, thus turning every incremental backup into a full backup. In other words, specifying -Xuse_ctime
also turns on -Xupdtu
.
The important points are as follows:
-
If
-Xuse_ctime
is not specified, then incremental test ismtime
,atimes
are left unchanged, and moved files might be missed. -
If
-Xuse_ctime
is specified, then incremental test isctime
,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 astat(2)
operation to determine whether a file represents a mount point. If a remotely mounted file system is down or not responding, then thestat(2)
operation can cause theobtar
process to hang.The
-Xchkmnttab
option causesobtar
to consult local mount table/etc/mnttab
before performing thesestat(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 thebackupoptions
policy. The-Xchkmnttab
option is overridden by-Xcrossmp
. -
-Xcrossmp
The
-Xcrossmp
option directsobtar
to cross all mount points even if the-Xchkmnttab
option is specified. You can specify the-Xcrossmp
option on the command line or in thebackupoptions
policy.
See Also:
obtar -c
Purpose
Use obtar -c
to create a single backup image. You might use obtar -c
to perform an on-demand backup or to back up data to a volume that you could transport to another site.
For NDMP backups, obtar
uses the default NDMP backup type set for the data service. You can override this setting by specifying a backup type at the host level or by using the NDMP policy. obtar
verifies that the user-specified backup type is valid for the data service that is used for the backup operation. However, the comparison used by obtar
is case-sensitive and recognizes only lowercase values. Thus, if you specify the backup type using upper case, obtar
does not recognize it as a valid backup type and uses the default NDMP backup type for the backup operation.
If the user ID (UID) or group ID (GID) of a file that is being backed up is greater than 2097151, Oracle Secure Backup substitutes the value 60002 for the UID or GID in the tar header file and returns a warning. This is because the maximum value for UID and GID, as defined by the POSIX standard (extended tar format), is 2097151. Therefore, when this backup is restored, the UID or GID for the restored file is 60002.
Syntax
obtar -c::=
obtar -c [ -f device ] [ -H host ] [ -G ] [ -v [ -v ] ] [ -z ] { [ -C directory ] pathname... }...
Semantics
You can specify several options with obtar -c
. This section describes those options that you are most likely to use. Refer to "obtar Options" to learn about additional obtar -c
options.
- -f device
-
Specifies the name of a tape device. If you do not specify
-f
, thenobtar
writes to the tape device specified by theTAPE
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
, thenobtar
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
), thenobtar
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
usespathname
as the location for the restored data. Theobtar -x
command, which you use to restore data, provides options that let you specify a differenthost
ordirectory
location for the restored data.If
pathname
refers to data available through a mount of a local or remote file system, thenobtar -c
does not cross the mount point unless you specify -Xcrossmp.You can also use the
-C
option to modify thepathname
information thatobtar
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, thenobtar
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
, thenobtar
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
, thenobtar
extracts the backup image at the current position of the volume. If you specifycur
, thenobtar
extracts the backup image at the volume's current position. This is the default. If you specifyfile-number
, thenobtar
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
, thenobtar
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 thereplacement
string forprefix
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, thenobtar
assumes a null string, which causesobtar
to remove theprefix
from everypathname
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 theprefix
or thereplacement
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, thenobtar
searches the entire backup image for subsequent copies of the requested files. - -R
-
Causes
obtar
to run withroot
access. To use-R
you must be a member of a class with theperform
restores
as
privileged
user
right. You are not required to use-R
if you are logged in asroot
. - -v
-
Displays the path names of the files and directories being restored. If you specify
-v -v
(or-vv
), thenobtar
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
, thenobtar
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
, thenobtar
reads from the tape device specified by theTAPE
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
, thenobtar
reads the backup image at the current position of the volume.If you specify
cur
, thenobtar
reads the backup image at the volume's current position. This is the default.If you specify
file-number
, thenobtar
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, thenobtar
lists the entire contents of the backup image at the volume's current location or at the location you specify with the-F
option.
Examples
Example B-11 Displaying the Contents of a Backup Image
This example displays the contents of the backup image located at the current position of the volume loaded on tape device tape1.
# obtar -t -f tape1 project/ project/file1 project/file2 project/file3
Example B-12 Displaying the Contents of a Backup Image on a Volume Set
To display the contents of a particular backup image on a volume set, use the -F
option. This example displays the contents of backup image 4.
# obtar -t -f tape1 -F 4 doc/ doc/chap1 doc/chap2 test/ test/file1 test/file2
Example B-13 Displaying Additional Information About a Backup Image
To display additional information about a backup image, use the -v
option. This example uses the -v
option to display additional information about backup image 4.
# obtar -t -v -f tape1 -F 4 drwxrwxr-x jane/rd 0 Feb 24 16:53 2000 doc/ -rw-r--r-- jane/rd 225 Feb 24 15:17 2000 doc/chap1 -rwxrwxr-x jane/rd 779 Feb 24 15:17 2000 doc/chap2 drwxrwxr-x jane/rd 0 Feb 24 16:55 2000 test/ -rwxrwxr-x jane/rd 779 Feb 24 16:54 2000 test/file1 -rw-r--r-- jane/rd 225 Feb 24 16:54 2000 test/file2
Example B-14 Displaying Information About a File in an Image
To display information about a particular file or directory that is contained in the backup image, include the file or directory name as the last argument on the command line. This example displays information about the directory test, which is contained in backup image 4.
# obtar -t -f tape1 -F 4 test test/ test/file1 test/file2
Example B-15 Displaying Information About Multiple Directories
You can specify multiple path names from the backup image. This example displays information about the directories test
and doc
. obtar
lists the directories in the order they appear in the backup image.
# obtar -t -f tape1 -F 4 test doc doc/ doc/chap1 doc/chap2 test/ test/file1 test/file2
Example B-16 Cataloging a File-System Backup Image
Use the -G
option to catalog the contents of a backup image. This example catalogs backup image 1 on the volume loaded into tape drive tape1 (only partial output is shown). In this example, the image contains a file-system backup. You can catalog only one backup image at a time.
# obtar -f tape1 -tG -F 1 Volume label: Volume tag: DEV100 Volume ID: VOL000001 Volume sequence: 1 Volume set owner: root Volume set created: Tue Nov 22 15:57:36 2012 Archive label: File number: 1 File section: 1 Owner: root Client host: osbsvr2 Backup level: 0 S/w compression: no Archive created: Tue Nov 22 15:57:36 2012 /home/someuser/ /home/someuser/.ICEauthority /home/someuser/.Xauthority /home/someuser/.aliases /home/someuser/.bash_history /home/someuser/.bash_logout /home/someuser/.bash_profile /home/someuser/.bashrc . . .
Example B-17 Cataloging an RMAN Backup Image
This example also catalogs backup image 1 on the volume loaded into tape drive tape1. In this example, the image contains an RMA backup of archived redo log files.
# obtar -f tape1 -tG -F 1 Volume label: Volume tag: ADE202 Volume ID: RMAN-DEFAULT-000002 Volume sequence: 1 Volume set owner: root Volume set created: Mon Feb 13 10:36:13 2006 Media family: RMAN-DEFAULT Volume set expires: never; content manages reuse Archive label: File number: 1 File section: 1 Owner: root Client host: osbsvr1 Backup level: 0 S/w compression: no Archive created: Mon Feb 13 10:36:13 2006 Backup piece name: 05hba0cd_1_1 Backup db name: ob Backup db id: 1585728012 Backup copy number: non-multiplexed backup Backup content: archivelog
obtar -zz
Purpose
Use obtar -zz
to display all Oracle Secure Backup labels on a volume.
Syntax
obtar -zz::=
obtar -zz [ -f device ]
Semantics
You can specify several options with obtar -zz
; this section describes the option that you are most likely to use. Refer to "obtar Options" to learn about additional obtar -zz
options.
- -f device
-
Specifies the name of a backup image file or tape device. If you omit the
-f
option, thenobtar
reads from the tape device specified by theTAPE
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 |
---|---|---|---|---|
x |
||||
x |
x |
x |
||
x |
x |
|||
x |
||||
x |
x |
|||
x |
x |
x |
x |
|
x |
x |
x |
||
x |
x |
|||
x |
||||
x |
x |
|||
x |
x |
x |
x |
|
x |
||||
x |
x |
|||
x |
x |
|||
x |
||||
x |
||||
x |
||||
x |
||||
x |
||||
x |
x |
|||
x |
x |
x |
x |
|
x |
||||
x |
||||
x |
||||
x |
x |
x |
||
x |
x |
|||
x |
||||
-Xcatalog | ||||
x |
x |
|||
x |
||||
x |
x |
|||
x |
x |
x |
||
x |
||||
x |
||||
x |
x |
|||
x |
||||
-Xinstance | ||||
x |
||||
x |
||||
x |
x |
x |
x |
|
x |
||||
x |
||||
x |
||||
x |
||||
x |
||||
x |
||||
x |
||||
x |
||||
x |
||||
x |
||||
x |
x |
Footnote 1
when -G
is also specified
Footnote 2
when -G
is also specified
- -A
-
Does not save Access Control Lists (ACLs), Context Dependent Files (CDFs), and other extended file-system attributes for files backed up on Hewlett-Packard platforms (HP-UX operating system). By default,
obtar
saves all file-system attributes for each file. When you restore these files on Hewlett-Packard platforms, the extended attributes are also restored.When you restore these files on other platforms,
obtar
ignores the ACL information.On Windows, Linux, and UNIX platforms, the
-A
flag causesobtar
to save only the primary data stream associated with each file, excluding the extended attributes and ACLs.See also:
"Oracle Secure Backup Support for Extended Attributes and Access Control Lists" for more information on performing backup and recovery with extended attributes and access control lists
- -b blocking-factor
-
Writes data in block sizes of
blocking-factor
multiplied by 512 bytes. By default,obtar
uses the blocking factor specified by the blockingfactor media policy. When you restore files,obtar
automatically determines the block size that was used when backing up the data. - -B
-
Performs multiple reads to fill a block. If you are using
obtar
with UNIX pipes or sockets, then the UNIXread
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 theobtar
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 todirectory
and backs up files relative to it.obtar
usesdirectory
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 forvolume-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, thenobtar
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 runningobtar -x
orobtar -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 directsobtar
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 forvolume-id-file
in the administrative directory on the administrative server. If you do not specify this option, thenobtar
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 theTAPE
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, thenobtar
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 configureobtar
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, wherevol-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, thenobtar
prompts you to load the necessary volume.If you specify the position as
cur
, thenobtar
writes or reads the backup image at the current volume position.If you specify
end
, thenobtar
writes the backup image immediately after the last existing backup image in the volume set.If you specify
file-number
, thenobtar
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
andobtar -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 causeobtar
to back up the data, not just the link text.If you include an explicit link path name when using
obtar -c
, thenobtar
backs up the data specified by that link whether you have used the-h
option or not. If you do not wantobtar
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
causesobtar
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, thenobtar
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 theobtar
-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 tofull
, and level 1 is identical toexincr
.If you use a
date-time
argument, thenobtar
saves only the data that was modified since that time. Note that using adate-time
argument does not create a true incremental backup because it cannot be used as a reference point for later incremental backups. Thedate-time
argument must be in the form appropriate to the locale in which you runobtar
. For the U.S., specifydate-time
in the following format:mm
/dd
[/yy
] [hh
[:mm
[:ss
]]]If you supply
hh
,hh
:mm
, orhh
:mm
:ss
as part ofdate-time
, then you must enclosedate-time
in quotes. If you do not supply the year (/yy
), thenobtar
uses the preceding 12 months. If you supplyhh
:mm
but notss
, thenobtar
useshh
: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, specifyon
to turn hardware compression on, and specifyoff
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 withobtar -c
, thenobtar
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 thels
--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 withobtar -t
as shown in the following example:obtar -t -f tape1 -q 000045020008
- -R
-
Runs
obtar
withroot
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 asroot
. - -s,prefix,[replacement,]
-
Substitutes
replacement
for each occurrence ofprefix
in all path names that are being restored.prefix
must include the first part of the original path name. If you omitreplacement
, thenobtar
removes all occurrences ofprefix
in all path names being restored. If the character does not occur in either theprefix
or thereplacement
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 theobtar
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 thels -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
, thenobtar
writes verbose information about files, which is similar to the output of thels -l
command, to standard error (obtar -c
), or standard output (obtar -x
).Note:
The user ID (UID) or group ID (GID) reported by the
-v
option might not match the actual UID or GID for a file. The maximum values for UID and GID are defined by the POSIX standard (extended tar format). During a backup operation, if Oracle Secure Backup encounters a file whose UID or GID exceeds the maximum (2097151) that fits in a tar header, then it substitutes 60002 as the UID or GID and returns a warning. The exit status of the backup reflects the presence of such warnings. - -V
-
Prints the version of
obtar
and exits. - -w
-
Directs
obtar
to check for and honor advisory file locks before backing up or restoring a file. If a lock is set, thenobtar
displays a warning message and skips the file. - -Xallowdiffspldev
-
By default, you can restore a raw partition only to a block device that has the same major or minor number as the block device to which the partition was backed up. To restore a raw partition to a block device whose major or minor numbers are different from number of the block device to which the partition was backed up, use the -
Xallowdiffspldev
option.Note:
The
Xallowdiffspldev
option is only available starting with Oracle Secure Backup 10.3.0.2.0. - -Xcatalog
- Allows cataloging of a single instance from a disk pool or cloud container device. Use this option with the
-Xinstance
option to specify the instance UUID to be imported. - -Xchkmnttab
-
Causes
obtar
to consult the local mount table (/etc/mnttab
) before performingstat(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 thebackupoptions
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.
- -Xinstance
-
Specifies a single backup image instance UUID to be cataloged from a disk pool device or cloud container device. This option must be used in conjunction with the
-Xcatalog
option. The following is a sample command issued on the media server that uses theXinstance
option:# obtar -Xcatalog -Xinstance:8d866afc-c1cf-1034-a202-0021f618cfbf -f disk1
- -Xkv:time_spec
-
Specifies the length of time a volume should be retained.
time_spec
isdisabled
(no retention time),forever
, orn tu
, wheretu
is one ofsecs
(or seconds),mins
(minutes),hrs
(hours),days
,wks
(weeks),mos
(months), oryrs
(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
, thenobtar
does not back up this directory or any of its subdirectories.Note:
TheXmarkerfiles
option is deprecated in Oracle Secure Backup Release 18.1 and may be desupported in a future release. - -Xnice:val
-
Directs
obtar
to set thenice(1)
value for the backup or restore process toval
. This value is propagated to any local and remote subprocesses spawned byobtar
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, thenobtar
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 originalatime
. 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 runutime(2)
calls to reset access times on files being backed up. This parameter controls the size of the input queue for theutime
helper. Linux and UNIX only. - -Xuse_ctime
-
Directs
obtar
, when performing an incremental backup, to use thectimes
(inode change times) rather thanmtimes
(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. - -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 theretainbackupmetrics
policy.See Also:
- -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 UNIXcompress(1)
utility before writing them to the backup image. If the files are compressed or would not shrink if compressed, thenobtar
does not compress them. When you restore files that have been compressed,obtar
automatically decompresses them unless you specify-Z
to suppress decompression.It is almost always preferable to rely on the tape drive's hardware compression capability, if it is available.
Note:
As of Oracle Secure Backup 12.2.0.1, new backups are not allowed to compress data using the
-Z
option. The-Z
option is retained only for use in restoring older compressed legacy backups with therestore
command.