From 3d0c60d004644630f1431ce486e76adcc829e288 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 17 Feb 2020 17:12:14 +0100 Subject: docs: filesystems: convert ocfs2-online-filecheck.txt to ReST - Add a SPDX header; - Add a document title; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add it to filesystems/index.rst. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/6007166acc3252697755836354bd29b5a5fb82aa.1581955849.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/filesystems/index.rst | 1 + .../filesystems/ocfs2-online-filecheck.rst | 99 ++++++++++++++++++++++ .../filesystems/ocfs2-online-filecheck.txt | 94 -------------------- 3 files changed, 100 insertions(+), 94 deletions(-) create mode 100644 Documentation/filesystems/ocfs2-online-filecheck.rst delete mode 100644 Documentation/filesystems/ocfs2-online-filecheck.txt diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 62be53c4755d..f3a26fdbd04f 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -76,6 +76,7 @@ Documentation for filesystem implementations. nilfs2 nfs/index ntfs + ocfs2-online-filecheck overlayfs virtiofs vfat diff --git a/Documentation/filesystems/ocfs2-online-filecheck.rst b/Documentation/filesystems/ocfs2-online-filecheck.rst new file mode 100644 index 000000000000..2257bb53edc1 --- /dev/null +++ b/Documentation/filesystems/ocfs2-online-filecheck.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +OCFS2 file system - online file check +===================================== + +This document will describe OCFS2 online file check feature. + +Introduction +============ +OCFS2 is often used in high-availability systems. However, OCFS2 usually +converts the filesystem to read-only when encounters an error. This may not be +necessary, since turning the filesystem read-only would affect other running +processes as well, decreasing availability. +Then, a mount option (errors=continue) is introduced, which would return the +-EIO errno to the calling process and terminate further processing so that the +filesystem is not corrupted further. The filesystem is not converted to +read-only, and the problematic file's inode number is reported in the kernel +log. The user can try to check/fix this file via online filecheck feature. + +Scope +===== +This effort is to check/fix small issues which may hinder day-to-day operations +of a cluster filesystem by turning the filesystem read-only. The scope of +checking/fixing is at the file level, initially for regular files and eventually +to all files (including system files) of the filesystem. + +In case of directory to file links is incorrect, the directory inode is +reported as erroneous. + +This feature is not suited for extravagant checks which involve dependency of +other components of the filesystem, such as but not limited to, checking if the +bits for file blocks in the allocation has been set. In case of such an error, +the offline fsck should/would be recommended. + +Finally, such an operation/feature should not be automated lest the filesystem +may end up with more damage than before the repair attempt. So, this has to +be performed using user interaction and consent. + +User interface +============== +When there are errors in the OCFS2 filesystem, they are usually accompanied +by the inode number which caused the error. This inode number would be the +input to check/fix the file. + +There is a sysfs directory for each OCFS2 file system mounting:: + + /sys/fs/ocfs2//filecheck + +Here, indicates the name of OCFS2 volume device which has been already +mounted. The file above would accept inode numbers. This could be used to +communicate with kernel space, tell which file(inode number) will be checked or +fixed. Currently, three operations are supported, which includes checking +inode, fixing inode and setting the size of result record history. + +1. If you want to know what error exactly happened to before fixing, do:: + + # echo "" > /sys/fs/ocfs2//filecheck/check + # cat /sys/fs/ocfs2//filecheck/check + +The output is like this:: + + INO DONE ERROR + 39502 1 GENERATION + + lists the inode numbers. + indicates whether the operation has been finished. + says what kind of errors was found. For the detailed error numbers, + please refer to the file linux/fs/ocfs2/filecheck.h. + +2. If you determine to fix this inode, do:: + + # echo "" > /sys/fs/ocfs2//filecheck/fix + # cat /sys/fs/ocfs2//filecheck/fix + +The output is like this::: + + INO DONE ERROR + 39502 1 SUCCESS + +This time, the column indicates whether this fix is successful or not. + +3. The record cache is used to store the history of check/fix results. It's +default size is 10, and can be adjust between the range of 10 ~ 100. You can +adjust the size like this:: + + # echo "" > /sys/fs/ocfs2//filecheck/set + +Fixing stuff +============ +On receiving the inode, the filesystem would read the inode and the +file metadata. In case of errors, the filesystem would fix the errors +and report the problems it fixed in the kernel log. As a precautionary measure, +the inode must first be checked for errors before performing a final fix. + +The inode and the result history will be maintained temporarily in a +small linked list buffer which would contain the last (N) inodes +fixed/checked, the detailed errors which were fixed/checked are printed in the +kernel log. diff --git a/Documentation/filesystems/ocfs2-online-filecheck.txt b/Documentation/filesystems/ocfs2-online-filecheck.txt deleted file mode 100644 index 139fab175c8a..000000000000 --- a/Documentation/filesystems/ocfs2-online-filecheck.txt +++ /dev/null @@ -1,94 +0,0 @@ - OCFS2 online file check - ----------------------- - -This document will describe OCFS2 online file check feature. - -Introduction -============ -OCFS2 is often used in high-availability systems. However, OCFS2 usually -converts the filesystem to read-only when encounters an error. This may not be -necessary, since turning the filesystem read-only would affect other running -processes as well, decreasing availability. -Then, a mount option (errors=continue) is introduced, which would return the --EIO errno to the calling process and terminate further processing so that the -filesystem is not corrupted further. The filesystem is not converted to -read-only, and the problematic file's inode number is reported in the kernel -log. The user can try to check/fix this file via online filecheck feature. - -Scope -===== -This effort is to check/fix small issues which may hinder day-to-day operations -of a cluster filesystem by turning the filesystem read-only. The scope of -checking/fixing is at the file level, initially for regular files and eventually -to all files (including system files) of the filesystem. - -In case of directory to file links is incorrect, the directory inode is -reported as erroneous. - -This feature is not suited for extravagant checks which involve dependency of -other components of the filesystem, such as but not limited to, checking if the -bits for file blocks in the allocation has been set. In case of such an error, -the offline fsck should/would be recommended. - -Finally, such an operation/feature should not be automated lest the filesystem -may end up with more damage than before the repair attempt. So, this has to -be performed using user interaction and consent. - -User interface -============== -When there are errors in the OCFS2 filesystem, they are usually accompanied -by the inode number which caused the error. This inode number would be the -input to check/fix the file. - -There is a sysfs directory for each OCFS2 file system mounting: - - /sys/fs/ocfs2//filecheck - -Here, indicates the name of OCFS2 volume device which has been already -mounted. The file above would accept inode numbers. This could be used to -communicate with kernel space, tell which file(inode number) will be checked or -fixed. Currently, three operations are supported, which includes checking -inode, fixing inode and setting the size of result record history. - -1. If you want to know what error exactly happened to before fixing, do - - # echo "" > /sys/fs/ocfs2//filecheck/check - # cat /sys/fs/ocfs2//filecheck/check - -The output is like this: - INO DONE ERROR -39502 1 GENERATION - - lists the inode numbers. - indicates whether the operation has been finished. - says what kind of errors was found. For the detailed error numbers, -please refer to the file linux/fs/ocfs2/filecheck.h. - -2. If you determine to fix this inode, do - - # echo "" > /sys/fs/ocfs2//filecheck/fix - # cat /sys/fs/ocfs2//filecheck/fix - -The output is like this: - INO DONE ERROR -39502 1 SUCCESS - -This time, the column indicates whether this fix is successful or not. - -3. The record cache is used to store the history of check/fix results. It's -default size is 10, and can be adjust between the range of 10 ~ 100. You can -adjust the size like this: - - # echo "" > /sys/fs/ocfs2//filecheck/set - -Fixing stuff -============ -On receiving the inode, the filesystem would read the inode and the -file metadata. In case of errors, the filesystem would fix the errors -and report the problems it fixed in the kernel log. As a precautionary measure, -the inode must first be checked for errors before performing a final fix. - -The inode and the result history will be maintained temporarily in a -small linked list buffer which would contain the last (N) inodes -fixed/checked, the detailed errors which were fixed/checked are printed in the -kernel log. -- cgit