cvfsck - Check and Recover a Xsan Volume
cvfsck [options] [VolName] [VolPath]
The cvfsck program can check and repair Xsan file system metadata cor-
ruption due to a system crash, bad disk or other catastrophic failure.
This program also has the ability to list all of the existing files and
their pertinent statistics, such as inode number, size, file type and
location in the volume.
If the volume is active, it may only be checked in a Read-only mode. In
this mode, modifications are noted, but not committed. The -n option
may be used to perform a read only check as well.
The file system checking program must be run on the machine where the
File System Services are running. cvfsck reads the configuration file
and compares the configuration against the metadata it finds. If there
are inconsistencies in the metadata, the volume is repaired to resolve
these issues. It is important that the configuration file (see
snfs_config(5)) accurately reflects the current state of the volume. If
you need to change a parameter in a current configuration, save a copy
of the configuration first.
NOTE: If no action flags are specified (-C, -e, -f, -g, -j, -F, -K, -M,
-p, -r, -s, -t, -w, -x), then cvfsck runs in a verbose read-only mode
equivalent to -nv.
-A Scan directories for name collisions that would occur on a case-
insensitive file system.
-a This option can only be used with -f and is used to tell cvfsck
to print totals (all). When used, a line is printed after each
storage pool showing how many free space fragments exist for
that storage pool. In addition, at the end of the run, this
options prints the grand total of free space fragments for all
Provide a specific path to a configuration file that is to be
used, overriding the implicit location. This option is used
when cvupdatefs invokes cvfsck as a sub-process to insure that
the volume meta data is consistent prior to doing a capacity or
-C Clobber a corrupted free inode list. No data will be lost in
this process, but metadata usage may be increased after running
this command. Only run this command if cvfsck cannot repair
-d Internal debug use. This option dumps a significant amount of
data to the standard output device.
-e Report statistics for extents in each file. This reporting
option enables all the same file statistics that the -r flag
enables. In addition, the -e flag enables statistic reporting
for each extent in a file. All extent data is displayed immedi-
ately following the parent file's information. See the -r flag
description for file statistics output. The extent stats are
output in the following order; Extent#, Stripe group, File rela-
tive block, Base block, End block No checking is done. This flag
implies -r and -n flags.
-f Report free space fragmentation. Each separate chunk of free
allocation blocks is tallied based on the chunk's size. After
all free chunks are accounted for, a report is displayed showing
the counts for each unique sized free space chunk. Free space
fragmentation is reported separately for each storage pool. The
free space report is sorted from smallest contiguous allocation
chunk to largest. The "Pct." column indicates percentage of the
storage pool space the given sized chunks make up. The "(sum)"
column indicates what percentage of the total storage pool space
is taken up by chunks smaller than, and equal to the given size.
The "Chunk Size" gives the chunk's size in volume blocks, and
the "Chunk Count" column displays how many instances of this
sized chunk are located in this storage pool's free space. For
more information on fragmentation see the snfsdefrag(1) page.
No checking is done. Implies -n flag. See also -a that is used
to get more output.
-g Print journal recovery log. With this flag cvfsck reports con-
tents of the metadata journal. For debugging use only. Implies
-i Print inode summary report. With this flag cvfsck scans the
inode list and reports inode statistics information then exits.
This includes a breakdown of the count of inode types, hard
links, and size of the largest directory. This is normally
reported as part of the 'Building Inode Index Database' phase
anyway but with this flag cvfsck exits after printing the inode
summary report and skips the rest of the operations. This
allows the inode summary report to run pretty fast. Implies -n
-j Execute journal recovery and then exit. Running journal recovery
will ensure all operations have been committed to disk, and that
the metadata state is up to date. It is recommended that cvfsck
is run with the -j flag before any read-only checks or volume
reports are run.
-J Dump raw journal to a file named jrnraw.dat and then exit. For
debugging use only.
-K Forces the journal to be cleared and reset. WARNING: Resetting
the journal may introduce metadata inconsistency. After the
journal reset has been completed, run cvfsck to verify and
repair any metadata inconsistency. Use this option with extreme
-l This option will log any problems to the system log. This is
mainly used on system startup where a file system check may be
automatically started by the Xsan File System Services.
Reassigns the FOUND (orphaned) files to another directory. The
argument inode which accompanies the -L flag is the inode number
of the directory which should receive any FOUND files. The Xsan
inode is a 64-bit value. On some platforms stat operations will
only return 32-bit values. If you are unsure, the 'dc pathname'
command can be used in cvfsdb to find the 64-bit inode number.
If the argument does not point to a valid directory cvfsck will
exit with an error. If the -L flag is not given, FOUND files
will be placed in the root of the Xsan file system.
-M Performs simple checks that attempt to determine whether a new
metadata dump is needed. If the checks find that a dump is
needed, cvfsck will exit with status 1 and print an explanation.
If the checks do not find that a dump is needed, cvfsck will
exit with status 0. If an error occurs while performing the
checks, cvfsck will print an explanation and exit with status 2.
This option is useful only on managed file systems. Note: these
checks are not exhaustive, and, in some cases, cvfsck will exit
with status 0 when a new dump is actually required.
-n This option allows a volume to be checked in a read-only mode.
The modifications that would have happened are described but are
not actually performed. A read-only volume check may display
errors if there are journaled volume transactions which have not
yet been committed. It is recommended that cvfsck is run with
the -j flag before a read-only check is run.
This option provides a method for deleting all files that have
blocks allocated on the given stripe group. All files that have
at least one data extent on the given stripe group will be
deleted, even if they have extents on other stripe groups as
well. WARNING: Use this option with extreme caution. This
option could remove files that the user did not intend to
remove, and there are no methods to recover files that have been
deleted with this option.
-r This report option shows information on file state. Information
for each file is output in the following order. Inode#, Mode,
Size, Block count, Extent count, Storage pools, Affinity, Path
THIS FUNCTIONALITY IS ONLY SUPPORTED ON MANAGED FILE SYSTEMS
Provides a method for restoring data on the given storage pool.
After cvfsck completes in this mode all files on the given stor-
age pool will be set to TAPE ONLY. All data blocks on the given
storage pool will be gone and subsequent access of these file
will trigger a retrieve from tape. NOTE: Running this command
may result in data loss.
-t Report files that trespass on the restricted areas of storage
pools. Space for these files may have been mistakenly allocated
in these areas by previous releases of Xsan, and any file
reported should be moved. No other checking is done.
This option specifies the directory where all temporary files
created by cvfsck will be placed. If this option is omitted all
temporary files will be placed in the system's default temporary
folder. NOTE: cvfsck does honor the use of TMPDIR/TEMP environ-
-v Use verbose reporting methods.
-w This option specifies that cvfsck is allowed to make modifica-
tions to the file system to correct any problems that are found.
-x Report statistics for input to a spread sheet. No checking is
done. Implies -e,-r and -n flags. All values are in decimal.
Data is comma separated and in this order: Inode#, Mode, Size,
Block Count, Affinity, Path, Extent Count, Extent Number, Stor-
age pool, File Relative Block, Base, End, Depth, Breadth
-X (Engineering use only.) Free all inodes in extended attribute
chains. Extended attributes present in these inodes will be
Specifies a volume to check. Otherwise all volumes on this sys-
tem will be displayed for selection.
Forces the program to use a location other than
/Library/Logs/Xsan/data to locate the volumes.
cvfsck will return one of the following condition codes upon exit.
0 - No error, no changes made to the file system
1 - Inconsistencies encountered, changes have been
made to the file system
- A read-only cvfsck will return 1 if journal replay is needed.
- A read-only cvfsck will only print the needed fixes and not
commit changes to the metadata.
2 - Fatal error, cvfsck run aborted
3 - Name collisions found, no repair needed
4 - Name collisions found, file system successfully repaired
It is strongly recommended that cvfsck be run first in read-only mode
to show the extent of any metadata corruption before attempting any
Unless running cvfsck in read-only mode, the file system should be
unmounted from all machines before a check is performed. In the event
that repairs are required and cvfsck modifies metadata, it will report
this at the end of the check. If this occurs, any machines that con-
tinue to mount the file system should be rebooted before restarting the
In order to ensure minimum run-time cvfsck should be run on an idle FSS
server. Extraneous I/O and processor usage will severely impact the
performance of cvfsck.
CRC checks are now done on all Windows Security descriptors. Windows
Security Descriptors with inconsistent CRC's are removed causing
affected files to inherit permissions from the parent folder.
Cvfsck limits the number of trace files to 100. It starts removing the
oldest trace file if the max number of trace files in
/Library/Logs/Xsan/data/VolName/trace is exceeded before a new file is
NOTE: On large file systems cvfsck may requires 100s of megabytes or
more of local system disk space for working files.
snfs_config(5) cvmkfile(1), cvupdatefs(1), cvadmin(1), snfsdefrag(1)
Xsan File System December 2011 cvfsck(1)