OCFS2-Devel Archive on lore.kernel.org
 help / color / Atom feed
From: akpm at linux-foundation.org <akpm@linux-foundation.org>
To: ocfs2-devel@oss.oracle.com
Subject: [Ocfs2-devel] [patch 24/28] ocfs2: add feature document for online file check
Date: Wed, 26 Aug 2015 15:12:25 -0700
Message-ID: <55de39c9.NAoA+ITBkmwk4Suv%akpm@linux-foundation.org> (raw)

From: Gang He <ghe@suse.com>
Subject: ocfs2: add feature document for online file check

This document describes the OCFS2 online file check feature.

OCFS2 is often used in high-availaibility systems.  However, OCFS2 usually
converts the filesystem to read-only on errors.  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) was introduced, which would return the EIO to the
calling process and terminate furhter 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.

Signed-off-by: Gang He <ghe@suse.com>
Cc: Goldwyn Rodrigues <rgoldwyn@suse.de>
Cc: Mark Fasheh <mfasheh@suse.com>
Cc: Joel Becker <jlbec@evilplan.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
---

 Documentation/filesystems/ocfs2-online-filecheck.txt |   95 ++++++++++
 1 file changed, 95 insertions(+)

diff -puN /dev/null Documentation/filesystems/ocfs2-online-filecheck.txt
--- /dev/null
+++ a/Documentation/filesystems/ocfs2-online-filecheck.txt
@@ -0,0 +1,95 @@
+		    OCFS2 online file check
+		    -----------------------
+
+This document will describe OCFS2 online file check feature.
+
+Introduction
+============
+OCFS2 is often used in high-availaibility systems. However, OCFS2 usually
+converts the filesystem to read-only on errors. 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) was introduced,
+which would return the EIO to the calling process and terminate furhter
+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 file for each OCFS2 file system mounting:
+
+  /sys/fs/ocfs2/<devname>/filecheck
+
+Here, <devname> indicates the name of OCFS2 volumn 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 <inode> before fixing, do
+
+  # echo "CHECK <inode>" > /sys/fs/ocfs2/<devname>/filecheck
+  # cat /sys/fs/ocfs2/<devname>/filecheck
+
+The output is like this:
+  INO		TYPE		DONE		ERROR
+39502		0		1		GENERATION
+
+<INO> lists the inode numbers.
+<TYPE> is what kind of operation you've done, 0 for inode check,1 for inode fix.
+<DONE> indicates whether the operation has been finished.
+<ERROR> 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 "FIX <inode>" > /sys/fs/ocfs2/<devname>/filecheck
+  # cat /sys/fs/ocfs2/<devname>/filecheck
+
+The output is like this:
+  INO		TYPE		DONE		ERROR
+39502		1		1		SUCCESS
+
+This time, the <ERROR> column indicates whether this fix is successful or not.
+
+3. The record cache is used to store the history of check/fix result. Its
+defalut size is 10, and can be adjust between the range of 10 ~ 100. You can
+adjust the size like this:
+
+  # echo "SET <size>" > /sys/fs/ocfs2/<devname>/filecheck
+
+Fixing stuff
+============
+On receivng 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.
_

             reply index

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2015-08-26 22:12 akpm at linux-foundation.org [this message]
2015-08-31 20:58 ` Mark Fasheh

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=55de39c9.NAoA+ITBkmwk4Suv%akpm@linux-foundation.org \
    --to=akpm@linux-foundation.org \
    --cc=ocfs2-devel@oss.oracle.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

OCFS2-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/ocfs2-devel/0 ocfs2-devel/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 ocfs2-devel ocfs2-devel/ https://lore.kernel.org/ocfs2-devel \
		ocfs2-devel@oss.oracle.com
	public-inbox-index ocfs2-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/com.oracle.oss.ocfs2-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git