.\" cvfsck.8: auto-generated, DO NOT EDIT .\" .\" Copyright 1999-2021. Quantum Corporation. All Rights Reserved. .\" StorNext is either a trademark or registered trademark of .\" Quantum Corporation in the US and/or other countries. .\" .\" Code start macro .de Cs .sp .ft C .in +0.3i .nf .. .\" Code end macro .de Ce .fi .in -0.3i .ft R .. .TH CVFSCK 8 "April 2021" "Xsan File System" .SH NAME cvfsck \- Check and Recover a Xsan Volume .SH SYNOPSIS .na .nh .HP .B cvfsck .RI [ options ] .RI [ VolName ] .RI [ VolPath ] .ad .hy .SH DESCRIPTION The \fBcvfsck\fR program can check and repair Xsan file system metadata corruption 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. .PP If the volume is active, it may only be checked in a \fIRead-only\fR mode. In this mode, modifications are noted, but not committed. The \fB\-n\fR option may be used to perform a read only check as well. .PP The file system checking program must be run on the machine where the File System Services are running. .PP \fBcvfsck\fR reads the configuration file and compares the configuration against a saved copy that is stored in the metadata. It is important that the configuration file (see .BR snfs_config (5)) accurately reflect the current state of the volume. If you need to change a parameter in a current configuration, save a copy of the configuration first or make sure .IR /Library/Logs/Xsan/data/ VolName /config_history/*.cfg. already has a recent copy. Once the configuration file has been validated with the metadata version, if the configuration file is different and \fBcvfsck\fP is not in read-only mode, the new configuration is stored in the metadata and the previous version is written to .IR /Library/Logs/Xsan/data/ VolName /config_history/*.cfg. . .PP After validating the configuration file, \fBcvfsck\fR reads all of the metadata, checks it for any inconsistencies, and the volume is repaired to resolve these issues or if in read-only mode, any problems are reported. .PP By default, modifications are first written to a file in the local volume instead of the Xsan disks. All fixes are made to this local file, including journal replay. When all problems are fixed and the run is complete, the user is asked if the changes should be copied to the actual Xsan disks. If the user responds "y", the changes are made. An answer of "n" indicates that the volume should not be changed. This allows the user to easily gauge the extent of problems with a volume before committing to the repair. The user can override this behavior with the \fB\-n\fR, \fB\-y\fR, and -\fB\-T\fR options. .SH OPTIONS \fBNOTE:\fR If no action flags are specified (\fB\-e\fR, \fB\-f\fR, \fB\-g\fR, \fB\-j\fR, \fB\-F\fR, \fB\-K\fR, \fB\-M\fR, \fB\-p\fR, \fB\-r\fR, \fB\-s\fR, \fB\-t\fR, \fB\-w\fR, \fB\-x\fR, \fB\-q\fR), then cvfsck runs in a verbose read-only mode equivalent to \fB\-nv\fR. .IP \fB-4\fR If there are files with unconverted or partially converted xattr chains that contain xattrs greater than 4KiB in length, destroy the oversized xattrs so conversion can continue. Use with caution. .IP \fB-A\fR Scan directories for name collisions that would occur on a case-insensitive file system. Note that the FSM must be stopped when using this option. .IP \fB\-a\fR This option can only be used with \fB\-f\fP and is used to tell \fBcvfsck\fR 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 storage pools. .IP "\fB\-B\fP \fIseparator\fP" Use \fIseparator\fP instead of comma (,) for the character used to partition fields when the \fB-x\fP option is specified. .IP "\fB\-c\fP \fIpathname\fP" Provide a specific path to a configuration file that is to be used, overriding the implicit location. This option is used when \fBcvupdatefs\fR invokes \fBcvfsck\fR as a sub-process to insure that the volume meta data is consistent prior to doing a capacity or stripegroup expansion. .IP \fB\-d\fR Internal debug use. This option dumps a significant amount of data to the standard output device. .IP \fB\-e\fR Report statistics for extents in each file. This reporting option enables all the same file statistics that the \fB-r\fR flag enables. In addition, the \fB-e\fR flag enables statistic reporting for each extent in a file. All extent data is displayed immediately following the parent file's information. See the \fB-r\fR flag description for file statistics output. The extent stats are output in the following order; \fIExtent#, Stripe group, File relative block, Base block, End block\fR No checking is done. This flag implies \fB-r\fR and \fB-n\fR flags. No tracing is enabled for this report option. .IP \fB\-E\fR Erase i.e. "scrub" on disk free space. Cvfsck will write zeros over all free space on the disk. It works in conjunction with the \fB-P\fR option that reports the last block actually scrubbed in case of a crash during a scrub operation. This is intended for Linux. .IP \fB\-f\fR 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 .BR snfsdefrag (1) and .BR sgdefrag (8) pages. No checking is done. Implies \fB-n\fR flag. See also \fB-a\fP that is used to get more output. .IP "\fB\-F\fR This option causes \fBcvfsck\fR to make use of the compressed cache even when the configured value of bufferCacheSize is less than or equal to 1GB. It also sizes the cache to hold all metadata which can dramatically improve performance for aged file systems having large file counts. This option can cause \fBcvfsck\fR to use a lot of memory, so it is advisable to first obtain an estimate using the \fB\-q\fR option. .IP \fB\-g\fR Print journal recovery log. With this flag cvfsck reports contents of the metadata journal. For debugging use only. Implies \fB-n\fR flag. .IP \fB\-i\fR 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 \fB-n\fR flag. .IP \fB\-j\fR 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 \fB-j\fR flag before any read-only checks or volume reports are run. .IP \fB\-J\fR Dump raw journal to a file named jrnraw.dat and then exit. For debugging use only. .IP \fB\-K\fR Forces the journal to be cleared and reset. \fBWARNING:\fR 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 caution. .IP \fB\-l\fR 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. .IP \fB\-L\fR This option forces all orphaned inodes (valid inodes which are not linked in to the directory tree) to be reattached in the lost+found directory. If this option is not present, cvfsck examines the RPL attribute on the inodes and tries to reattach them to the directory that used to hold them. In either usage, it tries to name the inodes using the name in the RPL attribute. If there is no RPL attribute, the inode number is used as a name. If that name already exists, the inode will be reattached using that name followed by a dash and a random number. .IP \fB\-M\fR 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. .IP "\fB\-m\fP \fIsize\fP" This option is used to specify the amount of memory in bytes to be used for the internal cache used to hold inode information. For larger file systems, this can improve the performance of \fBcvfsck\fR. Note that the memory estimate produced using the \fB-q\fR option will be increased by the amount specified with this option. The 'k', 'm', and 'g' extensions are recognized for this option. For example, \fB-m 2g\fR can be used to specify 2GB. .IP \fB\-n\fR This option allows a volume to be checked in a \fBread-only\fR mode. Modifications are written to a file in the local volume instead of the Xsan disks. All fixes that would be made if \fBcvfsck\fR was run without the \fB\-n\fR option are made to this local file, including journal replay. When the run is complete, the local file is thrown away. The volume itself is never changed. .IP \fB\-O\fR If cvfsck is run on a file system while the FSM for that file system is active, cvfsck runs in shared mode. This means that it runs in read-only mode and only a small subset of the usual checking is performed. This is because the FSM changing the file system may confuse a full cvfsck and cause problems. The \fB\-O\fR option causes cvfsck to perform full (read-only) checking anyway. Strange behavior may be observed. .IP "\fB\-p\fP \fIStripeGroupName\fP" 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. \fIWARNING:\fR 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. .IP \fB\-q\fR This option causes cvfsck to generate and estimate for disk and memory requirements and then exit. Any other options that will get used when performing the actual check should also be specified to improve estimate accuracy. For example, if the intent is to run \fBcvfsck -m2g -F\fP \fIVolName\fP, then to generate the estimate, run \fBcvfsck -q -m2g -F\fP \fIVolName\fP. Note that the base memory requirements will typically be around 600MB, so this should be taken into account when also using the \fB-m\fR option. .IP \fB\-Q\fR This option causes cvfsck to print qustat statistics just before exiting. .IP \fB\-P\fR Report progress of an Erase operation. This flag enables the writing of a file in \fI/Library/Logs/Xsan/debug\fP of the last block on a given strip group that has been scrubbed. The files are created on a stripe group by stripe group basis as .IR /Library/Logs/Xsan/data/cvfsck_ _sg . This is intended for Linux use. .IP \fB\-r\fR This report option shows information on file state. Information for each file is output in the following order. \fIInode#, Mode, Size, Block count, Extent count, Storage pools, Affinity, Path\fR No tracing is enabled for this report option. .IP \fB\-R\fR This option helps repair a file system which had cvmkfs accidentally run on it. First, cvfsck restores file system state which was saved by cvmkfs in .IR /Library/Logs/Xsan/debug/ VolName .cvmkfs . Then, it continues as usual to fix any other problems it may encounter. The COW layer treats the restoration of saved state the same as any other file system modification. This option is only useful if the accidental cvmkfs is detected before the file system is mounted and changed. Using it at any other time is not advised. If unsure, please contact customer support. .IP "\fB\-s\fP \fIStripeGroupName\fP" \fITHIS FUNCTIONALITY IS ONLY SUPPORTED ON MANAGED FILE SYSTEMS\fR .br Provides a method for restoring data on the given storage pool from a stored copy. \fBcvfsck\fR will truncate all files with data on the given storage pool. As such, all data blocks on that storage pool will be inaccessible and subsequent access of these files will trigger data retrieval from a stored copy. All data will be lost for files that do not have any stored copies. The \fBcvfsck\fR output will indicate whether or not the ALL_COPIES_MADE flag is set in the SNEA attribute for each truncated file. Files outside of all managed directories that have data on the given storage pool will be deleted from the file system. \fINOTE:\fR Use this option with extreme caution because it can result in permanent data loss. .IP "\fB\-T\fP \fIdirectory\fP" 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 environment variables. .IP \fB\-t\fR This option is used to check the work of the \fB-U\fR option on thin provisioned devices in the given file system. It causes \fBcvfsck\fP to print in \fBsn_dmap(1) -v\fR format, from the file system's perspective, an idea of what should be unmapped and mapped on each thin provisioned device in the given file system. One can then somewhat compare the \fBsn_dmap(1)\fR output with the \fBcvfsck -t\fR output as follows: any "mapped" space indicated by \fBsn_dmap(1)\fR must also be mapped in the \fBcvfsck\fR output. But, unmapped space from \fBsn_dmap(1)\fR may show up as mapped in the \fBcvfsck\fP output since the space has been allocated but not yet written. Going the other way, any mapped space from \fBcvfsck\fR may or may not be mapped from \fBsn_dmap\fP, depending if the allocated space was actually written. Any unmapped space (immediately after running \fBcvfsck -U\fP) must also appear as unmapped from \fBsn_dmap(1)\fP. In addition, this option verifies this final condition (checking ummapped space) printing lines where unmapped space is incorrectly still mapped. If all is copacetic, the following output appears for each device: \fIchecked \fBNNN\fP unmapped entries with 0 errors\fR where \fBNNN\fP is the number of unmapped pieces checked. This currently only works on Linux and is intended as a debugging tool for quality assurance and development. .IP \fB\-U\fR This option is for use with thin provisioned devices in the given file system. It causes UNMAPS or TRIMs operations for all file system free space. \fBCvfsck\fP will issue the appropriate UNMAP/TRIM device operations for every free chunk in the file system. See also the \fB\-t\fP option. This currently only works on Linux and only with Quantum-branded and Infinidat InfiniBox storage. .IP \fB\-v\fR Use verbose reporting methods. .IP \fB\-w\fR This option specifies that cvfsck is allowed to make modifications to the file system to correct any problems that are found. .IP \fB\-W\fR This option causes cvfsck to always clean up any orphaned "Wopens" inodes that may have been generated when an earlier metadata restore from the metadata archive was performed using an older version of Xsan. Normally, cvfsck will only clean up these inodes if other metadata inconsistencies are detected prior to the orphan inode phase. .IP \fB\-x\fR Report statistics. No checking is done. Implies \fB-e\fR,\fB-r\fR and \fB-n\fR flags. All values are in decimal. Data is output in this order: \fIInode#, Mode, Size, Block Count, Affinity, Path, Extent Count, Extent Number, Storage pool, File Relative Block, Base, End, Depth, Breadth\fR By default, fields are comma separated. However, the separating character can be changed using the -B option. See also the -z option. No tracing is enabled for this report option. .IP \fB\-X\fR (Engineering use only.) Free all inodes in extended attribute chains. Extended attributes present in these inodes will be deleted. .IP \fB\-y\fR Fix any problems found in the file system without prompting for confirmation. The default behavior is to display the extent of the changes that will be made and prompt for whether or not to make the changes. The fixes are first made to a file in a file on the local volume (specified by \fB\-T\fP). When all fixes are complete, they are copied into the actual Xsan disks. .IP \fB\-Y\fR Same behavior as \fB-y\fR except that the changes are not buffered through the local volume as they are by default. .IP \fB\-z\fR Enclose the Path field displayed by -x with double quotes. If the Path itself contains double quotes, replace each of them with two double quote characters. .IP \fB\-Z\fR Remove all NT Security Descriptors from the file system. This is useful when ACLs are being abandoned to allow the use of the unixPermBits Security Model. This option should only be used when recommended by Apple support. All StorNext systems must first unmount the file system prior to running cvfsck -Z since it modifies the metadata causing the FSM to prevent currently mounted clients from reconnecting. Running cvfsck -Z can take a long time for large file systems because all inodes have to be scanned for security descriptors. Also, since the metadata is updated by cvfsck -Z, if the \fBmetadataArchive\fR parameter is set to true in the file system configuration file, a new metadata archive will be generated when the FSM is restarted. Note that when running cvfsck -Z, the file system must be configured such that the securityModel is NOT \fBacl\fR, and enforceAcls, quotas, and windowsSecurity are all disabled either explicitly or by setting the securityModel to \fBunixpermbits\fR. After running cvfsck -Z, unix permissions on files and directories should be updated if needed. .IP \fIVolName\fR Specifies a volume to check. Otherwise all volumes on this system will be displayed for selection. .IP \fIVolPath\fR Forces the program to use \fIVolPath/data\fP instead of \fI/Library/Logs/Xsan/data\fR to locate the volumes. .SH EXIT VALUES cvfsck will return one of the following condition codes upon exit. .Cs 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 .Ce .SH NOTES It is strongly recommended that the user should not run cvfsck with the \fB\-y\fR or \fB\-Y\fR options until the extent of any metadata corruption is known. .PP Unless running \fBcvfsck\fR 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 \fBcvfsck\fR modifies metadata, it will report this at the end of the check. If this occurs, any machines that continue to mount the file system should be rebooted before restarting the file system. .PP In order to ensure minimum run-time \fBcvfsck\fR should be run on an idle FSS server. Extraneous I/O and processor usage will severely impact the performance of \fBcvfsck\fR. .PP 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. .PP Cvfsck limits the number of trace files to 100. It starts removing the oldest trace file if the max number of trace files in .IR /Library/Logs/Xsan/data/ VolName /trace is exceeded before a new file is created. .PP \fBNOTE:\fR On large file systems cvfsck may requires 100s of megabytes or more of local system disk space for working files. .PP If the output of -x is to be used with Excel, consider the use of the -z option so that lines having pathnames containing commas can be parsed. If the output of -x is to be used with Unix tools such as awk, Perl, or Python, consider using the -B option with a field separator such as '|' or similar that does not appear as a character in a pathname. .SH FILES .I /Library/Logs/Xsan/data/* .br .IR /Library/Logs/Xsan/data/ VolName /config_history/*.cfg. .br .I /Library/Preferences/Xsan/*.cfg .SH "SEE ALSO" .BR snfs_config (5) .BR cvmkfile (1), .BR cvupdatefs (8), .BR cvadmin (8), .BR sgdefrag (8), .BR snfsdefrag (1)