0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =====================================
0004 OCFS2 file system - online file check
0005 =====================================
0006
0007 This document will describe OCFS2 online file check feature.
0008
0009 Introduction
0010 ============
0011 OCFS2 is often used in high-availability systems. However, OCFS2 usually
0012 converts the filesystem to read-only when encounters an error. This may not be
0013 necessary, since turning the filesystem read-only would affect other running
0014 processes as well, decreasing availability.
0015 Then, a mount option (errors=continue) is introduced, which would return the
0016 -EIO errno to the calling process and terminate further processing so that the
0017 filesystem is not corrupted further. The filesystem is not converted to
0018 read-only, and the problematic file's inode number is reported in the kernel
0019 log. The user can try to check/fix this file via online filecheck feature.
0020
0021 Scope
0022 =====
0023 This effort is to check/fix small issues which may hinder day-to-day operations
0024 of a cluster filesystem by turning the filesystem read-only. The scope of
0025 checking/fixing is at the file level, initially for regular files and eventually
0026 to all files (including system files) of the filesystem.
0027
0028 In case of directory to file links is incorrect, the directory inode is
0029 reported as erroneous.
0030
0031 This feature is not suited for extravagant checks which involve dependency of
0032 other components of the filesystem, such as but not limited to, checking if the
0033 bits for file blocks in the allocation has been set. In case of such an error,
0034 the offline fsck should/would be recommended.
0035
0036 Finally, such an operation/feature should not be automated lest the filesystem
0037 may end up with more damage than before the repair attempt. So, this has to
0038 be performed using user interaction and consent.
0039
0040 User interface
0041 ==============
0042 When there are errors in the OCFS2 filesystem, they are usually accompanied
0043 by the inode number which caused the error. This inode number would be the
0044 input to check/fix the file.
0045
0046 There is a sysfs directory for each OCFS2 file system mounting::
0047
0048 /sys/fs/ocfs2/<devname>/filecheck
0049
0050 Here, <devname> indicates the name of OCFS2 volume device which has been already
0051 mounted. The file above would accept inode numbers. This could be used to
0052 communicate with kernel space, tell which file(inode number) will be checked or
0053 fixed. Currently, three operations are supported, which includes checking
0054 inode, fixing inode and setting the size of result record history.
0055
0056 1. If you want to know what error exactly happened to <inode> before fixing, do::
0057
0058 # echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/check
0059 # cat /sys/fs/ocfs2/<devname>/filecheck/check
0060
0061 The output is like this::
0062
0063 INO DONE ERROR
0064 39502 1 GENERATION
0065
0066 <INO> lists the inode numbers.
0067 <DONE> indicates whether the operation has been finished.
0068 <ERROR> says what kind of errors was found. For the detailed error numbers,
0069 please refer to the file linux/fs/ocfs2/filecheck.h.
0070
0071 2. If you determine to fix this inode, do::
0072
0073 # echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/fix
0074 # cat /sys/fs/ocfs2/<devname>/filecheck/fix
0075
0076 The output is like this:::
0077
0078 INO DONE ERROR
0079 39502 1 SUCCESS
0080
0081 This time, the <ERROR> column indicates whether this fix is successful or not.
0082
0083 3. The record cache is used to store the history of check/fix results. It's
0084 default size is 10, and can be adjust between the range of 10 ~ 100. You can
0085 adjust the size like this::
0086
0087 # echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set
0088
0089 Fixing stuff
0090 ============
0091 On receiving the inode, the filesystem would read the inode and the
0092 file metadata. In case of errors, the filesystem would fix the errors
0093 and report the problems it fixed in the kernel log. As a precautionary measure,
0094 the inode must first be checked for errors before performing a final fix.
0095
0096 The inode and the result history will be maintained temporarily in a
0097 small linked list buffer which would contain the last (N) inodes
0098 fixed/checked, the detailed errors which were fixed/checked are printed in the
0099 kernel log.
