.\ Common Development and Distribution License (the License"). .\ fields enclosed by brackets []" replaced with your own identifying .\ SAM-QFS_notice_end

NAME

qfsdump, qfsrestore - Dump or restore file system data

SYNOPSIS

qfsdump [ -dHoqTv ] [-B size ] [-b bl_factor ] [-I include_file ] [-X excluded-dir ] -f dump_file [ file… ]

qfsrestore [ -dilrRstTv2 ] [-B size ] [-b bl_factor ] -f dump_file [file… ]

DESCRIPTION

The qfsdump command creates a dump file of the control structures and data of each specified file. If the file is a directory, qfsdump recursively adds the control structures and data of its subdirectories to the dump file. Any file specified with an absolute path will be stored in the dump file with an absolute path and any file specified with a relative path will be stored in the dump file with a relative path. If no file is specified, qfsdump creates a dump file of the control structures and data of the current relative directory (.) and its subdirectories.

The qfsrestore command uses the contents of the dump file to restore the control structures and data for all the files in the dump file or each specified file. If a file is specified, its path and filename must exactly match the path and filename in the dump file. Files are restored to the absolute or relative locations specified in the dump file, unless the -s option is specified. If the -s option is specified, all filenames with an absolute path in the dump file are restored relative to the current directory, using the entire path specified in the dump file.

Both qfsdump and qfsrestore require the -f dump_file parameter, where dump_file is the name of the dump file. If a - (dash) is specified for the dump_file, qfsdump will write the dump file to stdout or qfsrestore will read the dump file from stdin. The dump file data can be passed through appropriate filters, such as compression or encryption, after being written by qfsdump or before being read by qfsrestore.

Dump files can contain either POSIX or NFSv4 Access Control Lists (ACLs). Normally, qfsrestore restores each type of ACL to the filesystem supporting that type of ACL. If the dump file contains POSIX ACLs and the filesystem supports NFSv4 ACLs, the POSIX ACLs are automatically converted to NFSv4 ACLs. If the dump file contains NFSv4 ACLs and the filesystem supports POSIX ACLs, the ACLs are not converted, a warning is issued, and files are restored with empty ACLs.

If the filesystem contains extended attributes, qfsdump dumps them to the dump file and qfsrestore restores them. If the -t or -l options are specified, extended attribute names are listed separately with the keyword attribute after the base file name and then followed by the attribute name.

qfsdump and qfsrestore require the super-user for execution. Oracle recommends that a site create qfsdump dumps on a periodic basis as part of a disaster recovery plan.

OPTIONS

-d

Enable debugging messages. Useful only to Oracle to trace execution for verification purposes.

-H

(qfsdump only) Specifies the dump file is to be created without a dump header record, or the existing dump file has no header record. This option be used to create control structure dump files which can be concatenated using cat (see cat (1)).

-i

(qfsrestore only) Prints inode numbers of the files when listing the contents of the dump. See also the -l, -t, and -2 options.

-I include_file

(qfsdump only) Takes the list of files to dump from include_file. This file has one relative or absolute path to be dumped per line. After processing include_file, any [file] arguments from the command line are processed.

-l

(qfsrestore only) Prints one line per file similar to sls -l when listing the contents of the dump. (This option is the lower case letter `ell'.) See also the -i, -t, and -2 options.

-o

(qfsdump only.) Attempts to optimize disk reads when dumping data of small files or extended attributes. This feature batches together small files and reorders them based on their starting device position. It also attempts to prefetch disk blocks to more efficiently utilize devices. As a result this option may decrease the time required to run qfsdump, but may increase disk utilization during the dump. The resulting dump file will differ from the non-optimized case in both the order of content, and dump file size due to zero-padding differences.

-q

(qfsdump only) Suppresses printing of warning messages during the dump for those files which will be damaged should the dump be restored. By default, such warning messages are displayed.

-r

(qfsrestore only) Replaces existing files when restoring control structures if the existing files have an older modification time than the dumped files.

-R

(qfsrestore only) Replaces existing files when restoring control structures.

-s

(qfsrestore only) Causes leading slashes to be stripped from filenames prior to restoring them. This is useful if the dump was made with an absolute pathname, and it's now necessary to restore the dump to a different location. Any directories required for the restoration and not defined in the dump file are automatically created.

-t

(qfsrestore only) Instead of restoring the dump, qfsrestore will list the contents of the dump file. See also the -i, -l, and -2 options.

-T

Displays statistics at termination, including number of files and directories processed, number of errors and warnings, etc. For example:

qfsdump statistics:
            Files:              52020
            Directories:        36031
            Symbolic links:     0
            Resource files:     8
            File  archives:     0
            Damaged files:      0
            Files with data:    24102
            File  warnings:     0
            Errors:             0
            Unprocessed dirs:   0
            File data bytes:    0

The numbers after Files, Directories, Symbolic links, and Resource files are the counts of files, directories and symbolic links whose inodes are contained in the dump.

File archives refers to the number of archive images associated with the above Files, Directories, Symbolic links and Resource files. Damaged files refers to the number of Files, Directories, Symbolic links, and Resource files which are either already marked damaged (for a qfsdump), or were damaged During a qfsrestore, this message because of having no archive image (for a qfsrestore).

Files with data refers to the number of Files that have online (full or partial) data dumped or restored.

File warnings refers to the number of Files, Directories, Symbolic links and Resource files which would be damaged should the dump be restored (because they had no archive images at the time of the dump).

Errors refers to the number of error messages which were printed during the dump or restore. These errors are indications of a problem, but the problem is not severe enough to cause an early exit from qfsdump or qfsrestore. Examples of errors during restore are failing to create a symbolic link, failing to change the owner or group of a file. Errors which might occur during a dump include pathname too long, failing to open a directory for reading, failing to read a symbolic link or resource file, or finding a file with an invalid mode.

Unprocessed dirs refers to the number of directories which were not processed due to an error (such as being unable to create the directory).

File data bytes is the amount of file data dumped or restored.

-v

Prints file names as each file is processed. This option is superseded by options -l or -2.

(qfsdump only) -X excluded-dir

specifies directory paths to be excluded from the dump. Multiple (up to 10) directories may be excluded by using multiple -X parameters. A directory which resolves to. or NULL causes an error message to be issued.

-2

Prints two lines per file similar to sls -2 when listing the contents of the dump. See also the -i, -l, and -t options.

-B size

Specifies a buffer size in units of 512 bytes. Note that there are limits on the buffer size, as specified in the error message when the limits have been exceeded. The default buffer size is 512 * 512 bytes.

-b bl_factor

Specifies a blocking factor in units of 512 bytes. When specified, all I∕O to the dump image file is done in multiples of the blocking factor. There is no blocking done by default.

file…

Gives a list of files to be dumped or restored. Note that the names given to restore must match exactly the names as they are stored in the dump; you can use qfsrestore -t to see how the names are stored.

NOTES

qfsdump only supports full dumps of specified files and directories. Incremental dump support should be added at a future date.

qfsdump dumps all data of a sparse file, and qfsrestore will restore all data. This can lead to files occupying more space on dump files and on restored file systems than anticipated. Support for sparse files should be added at a future date.

ERRORS

Not an Oracle HSM file: This message means that you are attempting to operate on a file which is not contained in a StorageTek QFS file system.
file: Unrecognised mode (0x..): This message means that qfsdump is being asked to dump a file which is not a regular file, directory, symbolic link or request file. While StorageTek QFS allows the creation of block special, character special, fifo … files, these do not function correctly, and qfsdump does not attempt to dump them.
file: Warning! File will be damaged.: During a qfsdump, this message means that the file in question does not currently have any archive copies. The file is dumped to the qfsdump file, but if the qfsdump file is used to restore this file, the file will be marked damaged.
file: Warning! File is already damaged.: During a qfsdump, this message means that the file is currently marked damaged. During restore, the file will still be damaged.
file: File was already damaged prior to dump: During a qfsrestore, this message means that the file was dumped with the damaged flag set.
.: Not an Oracle HSM file.: This message means that you are attempting to dump files from a non-QFS file system or restore files from a qfsdump dump file into a non-QFS file system.
file: stat() id mismatch: expected: %d.%d, got %d.%d: During a qfsdump, this message indicates one of two things. If the %d. portions match, but the .%d portions differ, then a directory or file was deleted and recreated while qfsdump was operating on it. The file is not dumped. If the %d. portions do not match, then a serious error has been encountered; consult your service provider for help.
Corrupt samfsdump file. name length %d: During a qfsrestore, this message means that the pathname of a file to be restored was less than zero, or larger than MAXPATHLEN. This should not occur, so qfsrestore aborts.
Corrupt samfsdump file. %s inode version incorrect: During a qfsrestore, this message means that the inode for the indicated file was in an old format. This should not occur, so qfsrestore aborts.
file: pathname too long: During a qfsdump, this message indicates that the pathname of the indicated file is longer than 1024 characters. The file is not dumped.

EXAMPLES

The following example creates a control structure dump of the entire ∕sam file system:


example# cd ∕qfs1
example# qfsdump -f ∕destination∕of∕the∕dump∕qfsdump.today

To restore a file system dump to ∕qfs1:


example# cd ∕qfs1
example# qfsrestore -f ∕source∕of∕the∕dump∕qfsdump.yesterday