samfsdump, samfsrestore - Dumps or restores Oracle HSM file control structure data
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 …]
SUNWsamfs
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.
This command accepts the following options:
-b
bl_factorSpecifies 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_fileNames 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
sizeSpecifies 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_loadfileSpecifies 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.
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.
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
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.
The media type and Volume Serial Name (VSN)
in media_type.
vsn format.
The position on the media.
Either online
or partial
.
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
.
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
cat
(1),
sls
(1),
samdb
(1m).
You may encounter messages while using the samfsdump
or samfsrestore
command. The following list shows several
possible messages and their explanations:
Message
Explanation
: 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.
: 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.
: 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 was already damaged prior to dump
If received during a samfsrestore
, this means
that the file was dumped with the damaged
flag set.
: 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.
: 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.
: 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.