| Skip Navigation Links | |
| Exit Print View | |
|
Sun QFS and Sun Storage Archive Manager 5.3 Reference Manual Sun QFS and Sun Storage Archive Manager 5.3 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Sun QFS and Sun Storage Archive Manager 5.3 Reference Manual Sun QFS and Sun Storage Archive Manager 5.3 Information Library |
1. User Commands (Man Pages Section 1)
2. Maintenance Commands (Man Pages Section 1M)
3. Library Functions (Man Pages Section 3)
4. Library Functions (Man Pages Section 3X)
5. File Formats (Man Pages Section 4)
NAME
samfsdump, samfsrestore - Dumps or restores SAM-QFS file
control structure data
SYNOPSIS
samfsdump [-b bl_factor] [-d] -f dump_file [-n] [-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 a SAM-QFS file system.
The samfsdump command creates a dump file, as follows:
o 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.
o If an individual file is specified for file, the samfsdump
command creates a dump file containing the control
structures for that individual file.
o 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.
You must be logged in as superuser (root) in order to
execute the samfsdump and samfsrestore commands. Sun
Microsystems 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 Corporation 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(1M) 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.
-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 -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 Sun 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:
o d indicates a directory.
o f indicates a regular file.
o l indiactes a symbolic link.
o R indicates a removable media file.
o I indicates a segment index.
o 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:
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:
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 Sun QFS and SAM-QFS 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 a SAM-FS file.
You are attempting to dump files from a
file system that is not a Sun QFS or
SAM-QFS file system, or you are
attempting to restore files from a
samfsdump dump file into a file system
that is not a Sun QFS or SAM-QFS 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.
|