1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun===================================== 4*4882a593SmuzhiyunOCFS2 file system - online file check 5*4882a593Smuzhiyun===================================== 6*4882a593Smuzhiyun 7*4882a593SmuzhiyunThis document will describe OCFS2 online file check feature. 8*4882a593Smuzhiyun 9*4882a593SmuzhiyunIntroduction 10*4882a593Smuzhiyun============ 11*4882a593SmuzhiyunOCFS2 is often used in high-availability systems. However, OCFS2 usually 12*4882a593Smuzhiyunconverts the filesystem to read-only when encounters an error. This may not be 13*4882a593Smuzhiyunnecessary, since turning the filesystem read-only would affect other running 14*4882a593Smuzhiyunprocesses as well, decreasing availability. 15*4882a593SmuzhiyunThen, a mount option (errors=continue) is introduced, which would return the 16*4882a593Smuzhiyun-EIO errno to the calling process and terminate further processing so that the 17*4882a593Smuzhiyunfilesystem is not corrupted further. The filesystem is not converted to 18*4882a593Smuzhiyunread-only, and the problematic file's inode number is reported in the kernel 19*4882a593Smuzhiyunlog. The user can try to check/fix this file via online filecheck feature. 20*4882a593Smuzhiyun 21*4882a593SmuzhiyunScope 22*4882a593Smuzhiyun===== 23*4882a593SmuzhiyunThis effort is to check/fix small issues which may hinder day-to-day operations 24*4882a593Smuzhiyunof a cluster filesystem by turning the filesystem read-only. The scope of 25*4882a593Smuzhiyunchecking/fixing is at the file level, initially for regular files and eventually 26*4882a593Smuzhiyunto all files (including system files) of the filesystem. 27*4882a593Smuzhiyun 28*4882a593SmuzhiyunIn case of directory to file links is incorrect, the directory inode is 29*4882a593Smuzhiyunreported as erroneous. 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunThis feature is not suited for extravagant checks which involve dependency of 32*4882a593Smuzhiyunother components of the filesystem, such as but not limited to, checking if the 33*4882a593Smuzhiyunbits for file blocks in the allocation has been set. In case of such an error, 34*4882a593Smuzhiyunthe offline fsck should/would be recommended. 35*4882a593Smuzhiyun 36*4882a593SmuzhiyunFinally, such an operation/feature should not be automated lest the filesystem 37*4882a593Smuzhiyunmay end up with more damage than before the repair attempt. So, this has to 38*4882a593Smuzhiyunbe performed using user interaction and consent. 39*4882a593Smuzhiyun 40*4882a593SmuzhiyunUser interface 41*4882a593Smuzhiyun============== 42*4882a593SmuzhiyunWhen there are errors in the OCFS2 filesystem, they are usually accompanied 43*4882a593Smuzhiyunby the inode number which caused the error. This inode number would be the 44*4882a593Smuzhiyuninput to check/fix the file. 45*4882a593Smuzhiyun 46*4882a593SmuzhiyunThere is a sysfs directory for each OCFS2 file system mounting:: 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun /sys/fs/ocfs2/<devname>/filecheck 49*4882a593Smuzhiyun 50*4882a593SmuzhiyunHere, <devname> indicates the name of OCFS2 volume device which has been already 51*4882a593Smuzhiyunmounted. The file above would accept inode numbers. This could be used to 52*4882a593Smuzhiyuncommunicate with kernel space, tell which file(inode number) will be checked or 53*4882a593Smuzhiyunfixed. Currently, three operations are supported, which includes checking 54*4882a593Smuzhiyuninode, fixing inode and setting the size of result record history. 55*4882a593Smuzhiyun 56*4882a593Smuzhiyun1. If you want to know what error exactly happened to <inode> before fixing, do:: 57*4882a593Smuzhiyun 58*4882a593Smuzhiyun # echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/check 59*4882a593Smuzhiyun # cat /sys/fs/ocfs2/<devname>/filecheck/check 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunThe output is like this:: 62*4882a593Smuzhiyun 63*4882a593Smuzhiyun INO DONE ERROR 64*4882a593Smuzhiyun 39502 1 GENERATION 65*4882a593Smuzhiyun 66*4882a593Smuzhiyun <INO> lists the inode numbers. 67*4882a593Smuzhiyun <DONE> indicates whether the operation has been finished. 68*4882a593Smuzhiyun <ERROR> says what kind of errors was found. For the detailed error numbers, 69*4882a593Smuzhiyun please refer to the file linux/fs/ocfs2/filecheck.h. 70*4882a593Smuzhiyun 71*4882a593Smuzhiyun2. If you determine to fix this inode, do:: 72*4882a593Smuzhiyun 73*4882a593Smuzhiyun # echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/fix 74*4882a593Smuzhiyun # cat /sys/fs/ocfs2/<devname>/filecheck/fix 75*4882a593Smuzhiyun 76*4882a593SmuzhiyunThe output is like this::: 77*4882a593Smuzhiyun 78*4882a593Smuzhiyun INO DONE ERROR 79*4882a593Smuzhiyun 39502 1 SUCCESS 80*4882a593Smuzhiyun 81*4882a593SmuzhiyunThis time, the <ERROR> column indicates whether this fix is successful or not. 82*4882a593Smuzhiyun 83*4882a593Smuzhiyun3. The record cache is used to store the history of check/fix results. It's 84*4882a593Smuzhiyundefault size is 10, and can be adjust between the range of 10 ~ 100. You can 85*4882a593Smuzhiyunadjust the size like this:: 86*4882a593Smuzhiyun 87*4882a593Smuzhiyun # echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set 88*4882a593Smuzhiyun 89*4882a593SmuzhiyunFixing stuff 90*4882a593Smuzhiyun============ 91*4882a593SmuzhiyunOn receiving the inode, the filesystem would read the inode and the 92*4882a593Smuzhiyunfile metadata. In case of errors, the filesystem would fix the errors 93*4882a593Smuzhiyunand report the problems it fixed in the kernel log. As a precautionary measure, 94*4882a593Smuzhiyunthe inode must first be checked for errors before performing a final fix. 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunThe inode and the result history will be maintained temporarily in a 97*4882a593Smuzhiyunsmall linked list buffer which would contain the last (N) inodes 98*4882a593Smuzhiyunfixed/checked, the detailed errors which were fixed/checked are printed in the 99*4882a593Smuzhiyunkernel log. 100