snmetadump(1) snmetadump(1)
NAME
snmetadump - Save and process a copy of the Xsan File System metadata
SYNOPSIS
snmetadump -d [-c] [-bF] [-D <n>] [-f dump_file] __FsName__
snmetadump -a [-m [-s [-M]]] [-bF] [-D <n>] [-f dump_file] __FsName__
snmetadump -r [-bF] [-D <n>] [-f dump_file] __FsName__
snmetadump -j journal_file... [-bF] [-D <n>] [-f dump_file] __FsName__
snmetadump -x [-bF] [-D <n>] [-f dump_file] __FsName__
snmetadump -X [-bF] [-D <n>] [-f dump_file] __FsName__
DESCRIPTION
The snmetadump utility provides the ability to create a copy of the
volume metadata for use in restoring a volume after a disaster. If some
portion of the Xsan volume is lost, the volume metadata can be restored
from a copy of the metadata dump file.
In a managed Xsan environment the metadata is kept up to date using
special restore journal files. These restore journals describe the
metadata updates that must be applied to a metadata dump to bring the
dump up to date with the current volume metadata. In the case of a dis-
aster and metadata recovery all managed files on the volume will be re-
stored as long as they had been stored to tape. When the volume is ac-
cessed after the metadata has been restored all files are in the "tape-
only" state, meaning that the file will contain the data of the last
copy stored. On a managed volume the process of keeping a metadata dump
up to date by applying restore journal files is performed by the daily
backup processing.
NON-MANAGED USAGE
A Xsan metadata dump has limited uses in a non-managed environment. On
a non-managed volume the dump only matches the state of the metadata
until the volume manager (FSM) process is started. After this point
metadata and data will have changed and the dump file is out of date.
However, saving a copy of the metadata is valuable during significant
volume or hardware configuration changes, and during software upgrades.
If accidental misconfiguration or data loss is encountered the metadata
dump can be used to restore the state of the metadata.
To create an snmetadump manually:
1. Stop the FSM.
2. If feasible, run cvfsck to verify the correctness of the metada-
ta. This may take a significant amount of time depending on
file system size and speed.
3. Run snmetadump -cd __FsName__ to create a new metadump. This
may take a significant amount of time depending on file system
size and speed.
4. Restart the FSM.
If an issue arises requiring restoration of metadata, the following
procedure should be used:
1. Restore the original file system configuration file that was
present when the metadump was created.
2. Prepare the metadump for restore: snmetadump -am __FsName__
3. Restore the metadump: snmetadump -r [-f dump_file] __FsName__
Note that if restore journals are not enabled, restoring a metadump
will cause any changes to file system metadata made after the metadump
was created to be lost.
The metadump is only useful for restoring the state of the metadata
given a valid, consistent configuration file. It will not roll back
configuration changes or repair broken configurations.
METADATA RESIZING
The preferred way of expanding a volume is by adding stripe groups us-
ing the cvupdatefs utility. However, in some scenarios it is necessary
to resize existing stripe groups. In particular, this may be necessary
when recovering from a disk array failure where the replacement disk
array is not the same size as the original. The snmetadump utility
provides a limited mechanism to allow this.
The replacement stripe groups may have a different number of LUNs in
them and those LUNs may be of different sizes than the original LUNs.
No other aspect of the stripe group configuration may be changed or da-
ta loss may result.
In particular, the stripe breadth of the stripe groups cannot be al-
tered during restore, so it is important that the original stripe
breadth value is still suitable for the altered stripe group or perfor-
mance degradation may result.
If decreasing the size of stripe groups is required, the __FsName__.us-
age report file in the metadump directory should be consulted. This
report file is updated every time snmetadump applies restore journals
and indicates the minimum size that each stripe group could be de-
creased to, based on the existing data in the stripe group.
To restore metadata to stripe groups that have been resized by changing
the size of the LUNs, the number of LUNs, or both:
1. Create a backup copy of the volume configuration file and the
metadump file. Restore these files if the resize operation
should fail or need to be aborted for any reason.
2. Run snmetadump -a __FsName__ to optimize the metadump.
3. Alter the volume configuration file to include the desired LUNs
in each stripe group. Do not alter the number of stripe groups
or any other aspect of the storage layout.
4. Run snmetadump -a -s -m -M __FsName__ to prepare the metadump
for metadata restore when the size or number of metadata disks
has changed. The -M option disables the truncation of files for
file systems where StorageManager or SnPolicy is enabled. File
truncation is necessary and would normally occur when preparing
the metadump for restore in disaster recovery. So if the resiz-
ing of metadata disks is in conjunction with disaster recovery,
do not use the -M option.
5. Run snmetadump -r __FsName__ to restore the metadump.
6. Run cvfsck to verify correctness of the restored metadata. (Rec-
ommended)
NOTES
When saving a copy of the metadata it is recommended that copies of the
volume configuration files are saved too.
It is always recommended that cvfsck(1) is run before a metadata dump
is saved. This will ensure that there are no metadata inconsistencies
copied to the metadata dump.
WARNING: Incorrect usage of this utility can result in data loss. Al-
ways refer to the Xsan documentation before using this utility.
USAGE
-a Apply Metadata Changes - apply completed restore journals to
the metadump and optimize the dump. This option will also
close the current restore journal, open a new restore journal,
then locate and apply the restore journals that need to be ap-
plied to the metadata dump. The backup process will invoke sn-
metadump with this option as part of the nightly backup on a
managed volume. This operation must be performed in order for
storage manager to read the dump file.
-b Display the build information for this binary
-c This option can only be run with the -d option. Clean up meta-
data dump, restore journal and temporary files associated with a
volume. When a new metadata dump is generated, previous restore
journals are no longer needed or valid. When invoked with this
option, snmetadump will check the metadump directory for files
to clean up. This option cannot be undone, so it is recommended
that all existing dump and restore journal files be backed up
prior to execution.
-d Dump Metadata - Read in the volume metadata and save a copy to a
metadata dump file. This file can later be used to replace lost
metadata in the case of system failure. The FSM must be stopped
while the metadata dump is performed. It is recommended to use
cvfsck to check the consistency of the metadata before creating
a new metadump where feasible.
-D <n> Turn on debugging flags (useful for support personnel only).
-f dump_file
Specify the name of the dump file to create or process. If no -f
argument is given then the default dump file will be used. The
default is /Library/Logs/Xsan/database/metadumps/metadump.Vol-
Name.
-F Force the operation. Override the state of a meta-dump which is
undetermined or potentially incomplete. Only use this flag at
the recommendation of StorNext technical support.
-j journal_file
Apply the specified restore journal to the metadata dump. NOTE:
Normally, this option would be used only if there is a journal
that needs to be applied manually just prior to volume restora-
tion. This option is needed only if a journal needs to be ap-
plied outside of normal -a processing. After using -j to apply a
journal, snmetadump can no longer track which journals have or
need to be applied, so either the metadata dump must be used to
restore the volume or a new metadump needs to be created.
-m Prepare a metadata dump for restore. The -m flag must be pro-
vided with the -a flag. If the file system configuration indi-
cates storageManager is enabled, this process will also truncate
all files to allow for retrieval from tape after the restoration
process.
-r Restore Metadata - Read metadata state from the dump file and
rebuild the volume metadata. Metadump must be prepared for re-
store using the -m flag before restoring. All Xsan binaries and
configuration files must be restored before this step can be
processed.
-s Resize Stripe Groups - Modify the metadump to reflect modified
stripe group sizes in the configuration file. Must be used dur-
ing restore preparation in conjunction with the -m flag. See
above.
-x Examine a metadata dump - Verify the format of the metadata dump
-X Test the metadump status to verify that the metadump is valid
and usable by snmetadump. In addition this check will test the
metadump version to ensure that the metadump file is compatible
with this version of snmetadump. If the metadump is usable sn-
metadump will exit with a status of 0. If the metadump is not
usable snmetadump will exit with a status of 1.
MORE NOTES
On a managed volume it is important to note that snmetadump is a single
piece of a larger backup and restore procedure. Be sure to refer to the
Xsan documentation before attempting to use this utility.
Incorrect usage of this utility may result in data loss.
The snmetadump utility depends on adequate free metadata space to re-
cover file system metadata. It is recommended that managed Xsan file
system use exclusive metadata stripe groups to prevent data files from
taking up needed metadata space. In the case where the snmetadump util-
ity determines that there is not enough metadata space to manage disas-
ter recovery snmetadump will fail and recommend that an additional
metadata stripe group be added. See the cvupdatefs(1) man page for more
details on adding stripe groups.
RETURN VALUES
0 - Success
1 - Failure - There was an error processing the metadata dump
2 - Dump Busy - The dump is being processed by another instance of
snmetadump. Try again later. See MORE NOTES section.
FILES
/Library/Logs/Xsan/database/metadumps/
Default location of metadump files for managed file systems
/Library/Logs/Xsan/data/VolName/
Default location of metadump files for unmanaged file systems
metadump.VolName
Metadump file
metadump.VolName.lock
Temporary file lock for metadump file
restore_journal-VolName.seqno.*
Restore journal files.
VolName.usage
Metadump resizing report. See above.
SEE ALSO
snfs_config(5), cvmkfile(1), cvfsck(1), cvupdatefs(1), cvadmin(1)
Xsan File System December 2005 snmetadump(1)
Mac OS X 10.9.1 - Generated Sun Jan 5 15:18:24 CST 2014