NAME

samfsdump, samfsrestore - Dumps or restores Oracle HSM file control structure data

SYNOPSIS

samfsdump [-b bl_factor] [-d] -f dump_file [-n] [-o] [-q] [-P] [-u] [-U] [-v] [-B size] [-H] [-I include_file] [-S] [-T] [-W] [-X excluded_dir] [-Y] [-Z db_loadfile] [file …]

samfsrestore [-b bl_factor] [-d] -f dump_file [-g log_file] [-i] [-l] [-r] [-s] [-t] [-v] [-B size] [-H] [-R] [-S] [-T] [-Z db_loadfile] [-2] [file …]

AVAILABILITY

SUNWsamfs

DESCRIPTION

The samfsdump command creates a dump file containing control structure information for each specified file. This command must be entered after you have used the cd (1) command to change to the mount point of an Oracle HSM file system.

The samfsdump command creates a dump file, as follows:

• If nothing is specified for file, the samfsdump command creates a dump file containing the control structures for every file in the current directory and also for every file in the current directory's subdirectories.

• If an individual file is specified for file, the samfsdump command creates a dump file containing the control structures for that individual file.

• If a directory is specified for file, the samfsdump command creates a dump file containing the control structures for every file in that directory and also for every file in that directory's subdirectories.

Any file specified with an absolute path is stored in the dump file with an absolute path. Any file specified with a relative path is stored in the dump file with its relative path.

The samfsrestore command uses the contents of the dump file to restore control structures for all the files in the dump file or for each specified file. If a file is specified, its path and file name must match exactly what exists in the dump file. By default, all files are restored to the absolute or relative location as each file is described in the dump file. If the -s option is specified, however, all file names with an absolute path in the dump file are restored relative to the current directory, using the entire path as contained in the dump file.

The samfsdump command does not create a dump of any data associated with the files (unless the -P, -u or -U options are specified), so no data can be restored from this dump file. It is assumed that the data associated with the dumped files has been archived in some way. If a file for which no archive copy is available is dumped, a warning message is issued noting that this file will be marked as damaged when restored. When that file is restored from the dump file, it is marked as damaged by samfsrestore. Note that this warning can be explicitly suppressed by using the -q option.

If dump file contains ACLs, they could be either of POSIX ACLs or NFSv4 ACLs. Each type of ACL would normally be restored to the filesystem supporting that type of ACL. If the dump file contains NFSv4 ACLs and the filesystem supports POSIX ACLs, or the dump file contains POSIX ACLs and the filesystem supports NFSv4 ACLs, no conversion will be performed, a warning will be issued, and files will be restored with empty ACLs.

If the filesystem contains extended attributes, samfsdump will dump them to the dump file and samfsrestore will restore them. The data contents of an extended attribute is dumped to the dump file regardless of the -u or -U options. 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.

You must be logged in as superuser (root) in order to execute the samfsdump and samfsrestore commands. Oracle recommends that a site create samfsdump dumps on a periodic basis as part of a disaster recovery plan.

OPTIONS

This command accepts the following options:

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

-d

Enables debugging messages. This option is useful only to Oracle and is used to trace execution for verification purposes.

-f dump_file

Names the file to which the control structure data dump is written to (by samfsdump) or read from (by samfsrestore). You must specify a dump_file.

If a dash character (-) is specified for the dump_file, samfsdump writes the dump file to stdout and samfsrestore reads the dump file from stdin.

The dump file data can be passed through appropriate filters, such as compression or encryption, after being written by samfsdump or before being read by samfsrestore.

-g log_file

(samfsrestore only) Generates a file of online directories and files. For information on the format of this file, see the NOTES section of this man page.

-i

(samfsrestore only) Prints the inode numbers of the files when listing the contents of the dump. For more listing options, see -l, -t, and -2 options.

-I include_file

(samfsdump 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

(samfsrestore only) Prints one line per file. This option is similar to the sls (1) command's -l option when listing the dump contents. Note that this option is identified by the lowercase letter `l', not a number '1'. For more listing options, see the -i, -t, and -2 options.

-n

(Obsolete. samfsdump only.) Always uses the new header format. The new header is incompatible with samfsrestore prior to the 3.5.0 release level.

-o

(samfsdump 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 samfsdump, 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.

-P

(samfsdump only) Dumps the online data portions of files which are offline, but have partial data online. This option can considerably increase the size of the dump file, as data and metadata are both being dumped. You must take care to manage the increased size of the dump. This option can be used to move file partial data by piping the output of samfsdump to the input of samfsrestore.

-q

(samfsdump only) Suppresses warning messages for damaged files. By default, samfsdump writes warning messages for each file that would be considered damaged if the dump were restored.

-r

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

-s

(samfsrestore only) Removes leading slashes from file names prior to restoring them. This is useful if the dump was made with an absolute path name and the dump is being restored to a different location. Any directories required for the restoration and not defined in the dump file are automatically created.

-t

(samfsrestore only) Lists the content of the dump file rather than restoring the dump. For more listing options, see the -i, -l, and -2 options.

-u

(samfsdump only) Dumps the data portions of files without at least one archive copy. This option can considerably increase the size of the dump file, as data and metadata are both being dumped. You must take care to manage the increased size of the dump.

-U

(samfsdump only) Dumps the data portions of files which are online. This option can considerably increase the size of the dump file, as data and metadata are both being dumped. If this option is used with segmented files, the archive copy information is not preserved when the file is restored. You must take care to manage the increased size of the dump. This option can be used to move file systems by piping the output of samfsdump to the input of samfsrestore.

-v

Prints file names as each file is processed. This option is superseded by the -l or -2 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.

-H

For samfsdump, creates the dump file without a dump header record. For samfsrestore, declares that the existing dump file has no header record. This option can be used to create control structure dump files that can be concatenated using the cat command. For more information on this command, see the cat (1) man page.

-R

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

-S

Perform only a scan to create a db_loadfile with the -Z option. When using -S during samfsdump, no dump file is created and -f is not needed. During samfsrestore, -S used with -Z will create a db_loadfile from the dump file specified by \fb-f and no restore is performed.

-T

Displays statistics at command termination. These statistics include the number of files and directories processed, the number of errors and warnings, and other information. Example:

samfsdump statistics:
              Files:              52020
              Directories:        36031
              Symbolic links:     0
              Resource files:     8
              File segments:      0
              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 the Files, Directories, Symbolic links, and Resource files keywords are the counts of files, directories, symbolic links, and removable-media files whose inodes are contained in the dump.

File segments refers to the number of data segments associated with segmented files from the dump.

File archives refers to the number of archive images associated with the preceding Files, Directories, Symbolic links, and Resource files.

Damaged files refers to the number of Files, Directories, Symbolic links, and Resource files that are either already marked damaged (for a samfsdump) or were damaged during a restore because they had no archive image (for a samfsrestore).

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 that 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 that were printed during the dump or restore. These errors indicate a problem, but the problem is not severe enough to cause an early exit from samfsdump or samfsrestore. Examples of errors during a restore are failing to create a symbolic link and failing to change the owner or group of a file. Errors that might occur during a dump include having a path name 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 that were not processed due to an error, such as being unable to create the directory.

File data bytes refers to the size of data that was dumped (using options -P, -U, or -u) or restored.

-W

(Obsolete. samfsdump only.) Writes warning messages during the dump process for files that would be damaged if the dump were restored. This option is retained for compatibility. By default, these warning messages are now issued automatically. For more information on controlling this behavior, see the -q option, which suppresses warning messages.

-X excluded_dir

(samfsdump only) Specifies directory paths to be excluded from the dump. Relative paths without leading characters must be used, for example dir1∕dir2. The result is an empty directory dir1∕dir2 in the dump file. A directory that resolves to. or NULL generates an error message. Multiple (up to 10) directories can be excluded by using multiple -X options.

-Y

(samfsdump only) Specifies that the trailing list of files are lists of files to dump. Using this option helps improve samfsdump performance by reducing the number of path lookups. If - is specified as the trailing list, standard input is used.

Each list must have one line per file, with tab separated inode number, generation number, and file path. The path must is relative to where samfsdump is executed.

Example line: 1039 11 testdir2∕rtest_f_61

Example usage: samfsdump -Y -f samfs1.dump ∕path∕to∕filelist

Example pipelined: samdb dump samfs1 | samfsdump -Y -f samfs1.dump -

If a sideband mysql database is being used by the target SAM filesystem, then the file list can be generated using the samdb (1m) dump command.

-Z db_loadfile

Specifies that a samdb (1m) db_loadfile should be created as part of a samfsdump or samfsrestore. This file is used to populate a sideband mysql database using the samdb (1m) load command.

Use the -S option to only produce the db_loadfile without performing the usual samfsdump or samfsrestore operations. If - is specified for the load file standard output is used.

-2

(samfsrestore only) Writes two lines per file, similar to the sls (1) command's -2 option, when listing the contents of the dump. For more listing options, see the -i, -l, and -t options.

file …

Lists 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 samfsrestore -t to see how the names are stored.

NOTES

A samfsrestore should not be attempted on a StorageTek QFS shared file system client.

The samfsdump output files compress to less than 25% of their original size.

If the -g option is used, a log file is generated during file system restoration. This file contains one line per file that was online, or partially online, at the time the file was dumped. This line is divided into fields and contains the following information:

Field

Description

1

The file type, which is indicated by one of the following letters:

\(bu d indicates a directory.
\(bu f indicates a regular file.
\(bu l indiactes a symbolic link.
\(bu R indicates a removable media file.
\(bu I indicates a segment index.
\(bu S indicates a data segment.

2

The media type and Volume Serial Name (VSN) in media_type.vsn format.

3

The position on the media.

4

Either online or partial.

5

The path relative to the file system mount point.

After a samfsrestore command is issued, it is possible to restore files that were online, prior to the dump, back to their online state. You do this by using the script in ∕opt∕SUNWsamfs∕examples∕restore.sh.

EXAMPLES

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

example# cd ∕sam
example# samfsdump -f ∕destination∕of∕the∕dump∕samfsdump.today

To restore a control structure dump to ∕sam:

example# cd ∕sam
example# samfsrestore -f ∕source∕of∕the∕dump∕samfsdump.yesterday

To create a new samdb (1m) database load file of ∕sam:

example# cd ∕sam
example# samfsdump -SZ ∕destination∕samfsdbload.today
To create a dump of ∕sam using a list of files:
.nf
example# cd ∕sam
example# samfsdump -Y -f ∕destination∕of∕samfsdump.today ∕source∕of∕samfslist.today
To create a new samdb (1m) load file from an existing dump file:
.nf
example# samfsrestore -SZ ∕destination∕samfsdbload.today -f ∕source∕samfsdump.yesterday

SEE ALSO

cat (1), sls (1), samdb (1m).

DIAGNOSTICS

You may encounter messages while using the samfsdump or samfsrestore command. The following list shows several possible messages and their explanations:

Message

Explanation

file: Unrecognised mode (0x..)

samfsdump is being asked to dump a file that is not a regular file, directory, symbolic link, or removable media file. The StorageTek QFS and Oracle HSM file systems allow the creation of block special, character special, fifo, and other special files, but they do not function correctly. samfsdump does not attempt to dump them.

file: Warning! File will be damaged.

If received during a samfsdump, this means that the file in question does not currently have any archive copies. The file is dumped to the samfsdump file, but if the samfsdump file is used to restore this file, the file will be marked damaged.

file: Warning! File is already damaged.

If received during a samfsdump, means that the file is currently marked damaged. During restoration, the file will still be damaged.

file: File was already damaged prior to dump

If received during a samfsrestore, this means that the file was dumped with the damaged flag set.

file: File is now damaged

If received during a samfsrestore, this means that the file was dumped when it had no archive images. samfsdump and samfsrestore do not dump file data. They rely on the file's data having been archived. Because the file no longer has any data associated with it, it is marked damaged.

.: Not an Oracle HSM file.

You are attempting to dump files from a file system that is not a StorageTek QFS or Oracle HSM file system, or you are attempting to restore files from a samfsdump dump file into a file system that is not a StorageTek QFS or Oracle HSM file system.

file: stat() id mismatch: expected: %d.%d, got %d.%d

If received during a dump, this 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 samfsdump 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

If received during a restore, this means that the path name of a file to be restored was less than zero or larger than MAXPATHLEN. This should not occur. samfsrestore aborts.

Corrupt samfsdump file. %s inode version incorrect

During a restore, this means that a the inode for the indicated file was in an old format. This should not occur. samfsrestore aborts.

file: pathname too long

If received during a dump, this indicates that the path name of the indicated file is longer than 1024 characters. The file is not dumped.