요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
=====================================
4
OCFS2 file system - online file check
5
=====================================
7
This document will describe OCFS2 online file check feature.
9
Introduction
10
============
11
OCFS2 is often used in high-availability systems. However, OCFS2 usually
12
converts the filesystem to read-only when encounters an error. This may not be
13
necessary, since turning the filesystem read-only would affect other running
14
processes as well, decreasing availability.
15
Then, a mount option (errors=continue) is introduced, which would return the
16
-EIO errno to the calling process and terminate further processing so that the
17
filesystem is not corrupted further. The filesystem is not converted to
18
read-only, and the problematic file's inode number is reported in the kernel
19
log. The user can try to check/fix this file via online filecheck feature.
21
Scope
22
=====
23
This effort is to check/fix small issues which may hinder day-to-day operations
24
of a cluster filesystem by turning the filesystem read-only. The scope of
25
checking/fixing is at the file level, initially for regular files and eventually
26
to all files (including system files) of the filesystem.
28
In case of directory to file links is incorrect, the directory inode is
29
reported as erroneous.
31
This feature is not suited for extravagant checks which involve dependency of
32
other components of the filesystem, such as but not limited to, checking if the
33
bits for file blocks in the allocation has been set. In case of such an error,
34
the offline fsck should/would be recommended.
36
Finally, such an operation/feature should not be automated lest the filesystem
37
may end up with more damage than before the repair attempt. So, this has to
38
be performed using user interaction and consent.
40
User interface
41
==============
42
When there are errors in the OCFS2 filesystem, they are usually accompanied
43
by the inode number which caused the error. This inode number would be the
44
input to check/fix the file.
46
There is a sysfs directory for each OCFS2 file system mounting::
48
/sys/fs/ocfs2/<devname>/filecheck
50
Here, <devname> indicates the name of OCFS2 volume device which has been already
51
mounted. The file above would accept inode numbers. This could be used to
52
communicate with kernel space, tell which file(inode number) will be checked or
53
fixed. Currently, three operations are supported, which includes checking
54
inode, fixing inode and setting the size of result record history.
56
1. If you want to know what error exactly happened to <inode> before fixing, do::
58
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/check
59
# cat /sys/fs/ocfs2/<devname>/filecheck/check
61
The output is like this::
63
INO DONE ERROR
64
39502 1 GENERATION
66
<INO> lists the inode numbers.
67
<DONE> indicates whether the operation has been finished.
68
<ERROR> says what kind of errors was found. For the detailed error numbers,
69
please refer to the file linux/fs/ocfs2/filecheck.h.
71
2. If you determine to fix this inode, do::
73
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/fix
74
# cat /sys/fs/ocfs2/<devname>/filecheck/fix
76
The output is like this::
78
INO DONE ERROR
79
39502 1 SUCCESS
81
This time, the <ERROR> column indicates whether this fix is successful or not.
83
3. The record cache is used to store the history of check/fix results. It's
84
default size is 10, and can be adjust between the range of 10 ~ 100. You can
85
adjust the size like this::
87
# echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set
89
Fixing stuff
90
============
91
On receiving the inode, the filesystem would read the inode and the
92
file metadata. In case of errors, the filesystem would fix the errors
93
and report the problems it fixed in the kernel log. As a precautionary measure,
94
the inode must first be checked for errors before performing a final fix.
96
The inode and the result history will be maintained temporarily in a
97
small linked list buffer which would contain the last (N) inodes
98
fixed/checked, the detailed errors which were fixed/checked are printed in the
99
kernel log.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
고가용성을 위한 온라인 파일 검사
1-20이 문서는 OCFS2의 온라인 파일 검사 기능을 설명합니다. OCFS2는 고가용성 시스템에서 자주 사용되지만, 일반적인 오류 처리에서는 파일시스템을 읽기 전용으로 전환합니다. 한 파일에서 발생한 문제가 다른 실행 중인 프로세스까지 막아 가용성을 낮출 수 있다는 점이 이 기능의 출발점입니다.
`errors=continue` 마운트 옵션을 사용하면 오류를 일으킨 호출 프로세스에 `-EIO`를 반환하고 해당 처리를 중단하여 추가 손상을 막습니다. 파일시스템 전체는 읽기 전용으로 바뀌지 않으며, 문제가 있는 파일의 inode 번호가 커널 로그에 기록됩니다. 관리자는 그 번호를 온라인 filecheck 인터페이스에 전달하여 파일을 검사하거나 복구할 수 있습니다.
OCFS2 파일 작업에서 오류 감지→`errors=continue`가 호출자에 `-EIO` 반환→해당 처리 중단으로 추가 손상 방지→커널 로그에 문제 inode 번호 기록→관리자가 온라인 filecheck로 검사·복구
파일시스템 전체를 멈추지 않고 문제 inode를 격리하여 다루는 흐름입니다.
.. 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.
검사 범위와 운영상 제한
21-39이 기능의 목표는 클러스터 파일시스템을 읽기 전용으로 전환시켜 일상 운영을 방해할 수 있는 작은 문제를 파일 단위로 검사하고 고치는 것입니다. 초기 범위는 일반 파일이며, 장기적으로는 시스템 파일을 포함한 파일시스템의 모든 파일로 확대하는 것을 염두에 둡니다.
디렉터리에서 파일로 이어지는 링크가 잘못된 경우에는 파일 inode가 아니라 디렉터리 inode가 오류 대상으로 보고됩니다. 반면 파일 블록에 대응하는 할당 비트가 실제로 설정되었는지 확인하는 것처럼 다른 파일시스템 구성 요소와의 의존성을 광범위하게 조사해야 하는 오류는 온라인 filecheck의 범위가 아닙니다. 그런 경우에는 오프라인 `fsck`를 사용해야 합니다.
복구 작업은 자동화해서는 안 됩니다. 충분한 판단 없이 자동 복구를 수행하면 복구 전보다 손상이 커질 수 있으므로, 반드시 사용자의 상호작용과 명시적인 동의를 거쳐 실행해야 합니다.
구분대상권장 처리
온라인 검사일반 파일 중심의 작은 파일 단위 오류inode를 확인한 뒤 수동 검사·복구
디렉터리 링크 오류디렉터리와 파일 사이의 잘못된 링크디렉터리 inode를 오류 대상으로 사용
구성 요소 의존 오류할당 비트 등 전역 메타데이터와의 교차 검증오프라인 `fsck`
자동 복구사용자 판단 없는 반복 실행손상 확대 위험 때문에 금지
온라인 검사에 적합한 문제와 오프라인 검사가 필요한 문제를 구분합니다.
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.
sysfs 인터페이스와 검사 작업
40-70OCFS2 오류 메시지에는 대개 원인이 된 inode 번호가 함께 기록되며, 이 번호가 파일 검사와 복구의 입력값입니다. 마운트된 각 OCFS2 파일시스템에는 `/sys/fs/ocfs2/<devname>/filecheck` sysfs 디렉터리가 생깁니다. 여기서 `<devname>`은 이미 마운트된 OCFS2 볼륨 장치 이름입니다.
이 인터페이스는 inode 번호를 받아 커널 공간에 어떤 파일을 검사하거나 고칠지 전달합니다. 현재 지원하는 작업은 inode 검사, inode 복구, 검사·복구 결과 이력의 레코드 수 설정 세 가지입니다.
먼저 정확한 오류를 확인하려면 inode 번호를 `check`에 쓰고 같은 파일을 읽습니다. 결과의 `INO`는 inode 번호, `DONE`은 작업 완료 여부, `ERROR`는 발견한 오류 종류를 뜻합니다. 세부 오류 번호와 이름은 `linux/fs/ocfs2/filecheck.h`를 참조합니다.
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/check
# cat /sys/fs/ocfs2/<devname>/filecheck/checkINODONEERROR
395021GENERATION
inode 번호작업 완료 여부`filecheck.h`에 정의된 오류 종류
원문의 예시 출력과 각 열의 의미를 구조화했습니다.
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/<devname>/filecheck
Here, <devname> 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 <inode> before fixing, do::
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/check
# cat /sys/fs/ocfs2/<devname>/filecheck/check
The output is like this::
INO DONE ERROR
39502 1 GENERATION
<INO> lists the inode numbers.
<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.
복구 작업과 결과 이력 크기
71-88검사 결과를 바탕으로 해당 inode를 복구하기로 결정했다면 inode 번호를 `fix`에 쓰고 결과를 읽습니다. 이때 `ERROR` 열은 발견한 오류 종류가 아니라 복구 성공 여부를 나타냅니다. 원문의 예시는 inode `39502`에 대해 `DONE=1`, `ERROR=SUCCESS`를 반환합니다.
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/fix
# cat /sys/fs/ocfs2/<devname>/filecheck/fix레코드 캐시는 검사와 복구 결과의 최근 이력을 저장합니다. 기본 크기는 10이며 10부터 100 사이로 조정할 수 있습니다. 원하는 크기를 `/sys/fs/ocfs2/<devname>/filecheck/set`에 쓰면 됩니다.
# echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set`check`에 inode 번호 기록→`INO`, `DONE`, `ERROR` 결과 확인→사용자가 복구 여부 결정→`fix`에 같은 inode 번호 기록→`ERROR=SUCCESS` 등 복구 결과 확인→필요하면 `set`으로 이력 크기를 10~100에서 조정
복구 전에 반드시 검사를 먼저 수행하고 사용자가 결과를 확인합니다.
2. If you determine to fix this inode, do::
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/fix
# cat /sys/fs/ocfs2/<devname>/filecheck/fix
The output is like this::
INO DONE ERROR
39502 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 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 "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set
커널 내부 복구와 임시 이력
89-99파일시스템은 inode 번호를 받으면 inode와 파일 메타데이터를 읽습니다. 오류가 확인되면 이를 복구하고, 실제로 고친 문제를 커널 로그에 남깁니다. 안전 조치로 최종 복구를 실행하기 전에 반드시 같은 inode를 먼저 검사해야 합니다.
inode와 결과 이력은 작은 연결 리스트 버퍼에 임시로 유지됩니다. 이 버퍼에는 최근 검사하거나 복구한 마지막 `N`개 inode가 들어가며, 검사·복구한 세부 오류 내용은 커널 로그에 출력됩니다. 따라서 sysfs 결과 이력과 커널 로그를 함께 확인해야 작업의 전체 맥락을 알 수 있습니다.
inode 번호 수신→inode와 파일 메타데이터 읽기→사전 검사 결과 확인→확인된 오류 복구→최근 `N`개 결과를 연결 리스트에 임시 보관→세부 오류와 복구 내용을 커널 로그에 기록
입력 inode를 읽고 검증한 뒤 복구 결과를 임시 이력과 커널 로그에 남깁니다.
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.
요약·해설
ocfs2-online-filecheck.rst:1-99OCFS2 온라인 filecheck는 `errors=continue`로 파일시스템 전체의 읽기 전용 전환을 피하면서 오류 inode를 수동으로 검사·복구하는 인터페이스입니다. 커널 로그에서 inode를 확인하고 sysfs의 `check`, `fix`, `set` 파일을 순서와 목적에 맞게 사용합니다.
전역 메타데이터 의존성을 조사하는 오류는 오프라인 `fsck`의 대상이며, 자동 복구는 추가 손상 위험 때문에 금지됩니다. 복구 전 검사, 사용자 동의, sysfs 결과와 커널 로그의 교차 확인이 핵심 안전 절차입니다.
오류 inode 확인부터 수동 복구와 결과 검증까지의 요약입니다.