요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
================
uevents and GFS2
================
During the lifetime of a GFS2 mount, a number of uevents are generated.
This document explains what the events are and what they are used
for (by gfs_controld in gfs2-utils).
A list of GFS2 uevents
======================
1. ADD
------
The ADD event occurs at mount time. It will always be the first
uevent generated by the newly created filesystem. If the mount
is successful, an ONLINE uevent will follow. If it is not successful
then a REMOVE uevent will follow.
The ADD uevent has two environment variables: SPECTATOR=[0|1]
and RDONLY=[0|1] that specify the spectator status (a read-only mount
with no journal assigned), and read-only (with journal assigned) status
of the filesystem respectively.
2. ONLINE
---------
The ONLINE uevent is generated after a successful mount or remount. It
has the same environment variables as the ADD uevent. The ONLINE
uevent, along with the two environment variables for spectator and
RDONLY are a relatively recent addition (2.6.32-rc+) and will not
be generated by older kernels.
3. CHANGE
---------
The CHANGE uevent is used in two places. One is when reporting the
successful mount of the filesystem by the first node (FIRSTMOUNT=Done).
This is used as a signal by gfs_controld that it is then ok for other
nodes in the cluster to mount the filesystem.
The other CHANGE uevent is used to inform of the completion
of journal recovery for one of the filesystems journals. It has
two environment variables, JID= which specifies the journal id which
has just been recovered, and RECOVERY=[Done|Failed] to indicate the
success (or otherwise) of the operation. These uevents are generated
for every journal recovered, whether it is during the initial mount
process or as the result of gfs_controld requesting a specific journal
recovery via the /sys/fs/gfs2/<fsname>/lock_module/recovery file.
Because the CHANGE uevent was used (in early versions of gfs_controld)
without checking the environment variables to discover the state, we
cannot add any more functions to it without running the risk of
someone using an older version of the user tools and breaking their
cluster. For this reason the ONLINE uevent was used when adding a new
uevent for a successful mount or remount.
4. OFFLINE
----------
The OFFLINE uevent is only generated due to filesystem errors and is used
as part of the "withdraw" mechanism. Currently this doesn't give any
information about what the error is, which is something that needs to
be fixed.
5. REMOVE
---------
The REMOVE uevent is generated at the end of an unsuccessful mount
or at the end of a umount of the filesystem. All REMOVE uevents will
have been preceded by at least an ADD uevent for the same filesystem,
and unlike the other uevents is generated automatically by the kernel's
kobject subsystem.
Information common to all GFS2 uevents (uevent environment variables)
=====================================================================
1. LOCKTABLE=
--------------
The LOCKTABLE is a string, as supplied on the mount command
line (locktable=) or via fstab. It is used as a filesystem label
as well as providing the information for a lock_dlm mount to be
able to join the cluster.
2. LOCKPROTO=
-------------
The LOCKPROTO is a string, and its value depends on what is set
on the mount command line, or via fstab. It will be either
lock_nolock or lock_dlm. In the future other lock managers
may be supported.
3. JOURNALID=
-------------
If a journal is in use by the filesystem (journals are not
assigned for spectator mounts) then this will give the
numeric journal id in all GFS2 uevents.
4. UUID=
--------
With recent versions of gfs2-utils, mkfs.gfs2 writes a UUID
into the filesystem superblock. If it exists, this will
be included in every uevent relating to the filesystem.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
GFS2 uevent 개요와 ADD·ONLINE
1-35GFS2 mount가 유지되는 동안 kernel은 여러 uevent를 생성합니다. 이 문서는 각 event의 발생 시점과 `gfs2-utils`의 `gfs_controld`가 event를 사용하는 목적을 설명합니다.
`ADD`는 mount 시점에 발생하며 새로 생성된 filesystem이 내보내는 첫 번째 uevent입니다. mount가 성공하면 뒤이어 `ONLINE`이 발생하고, 실패하면 `REMOVE`가 발생합니다.
`ADD`에는 `SPECTATOR=[0|1]`과 `RDONLY=[0|1]` 두 environment variable이 있습니다. 두 값은 각각 filesystem의 spectator 상태와 read-only 상태를 나타냅니다.
spectator mount는 journal을 할당받지 않는 read-only mount입니다. 반면 `RDONLY=1`로 나타내는 일반 read-only mount에는 journal이 할당됩니다. 따라서 둘은 쓰기 금지라는 외형은 같아도 cluster journal 참여 여부가 다릅니다.
`ONLINE`은 mount 또는 remount가 성공한 뒤 생성되며 `ADD`와 같은 두 environment variable을 가집니다.
spectator와 `RDONLY` 변수를 동반하는 `ONLINE` uevent는 Linux 2.6.32-rc 이후에 추가된 비교적 새로운 interface입니다. 그보다 오래된 kernel은 이 event를 생성하지 않으므로 user space는 구형 kernel과의 호환성을 고려해야 합니다.
새 filesystem의 첫 ADD 이후 mount 결과에 따라 후속 event가 갈립니다.
두 event가 전달하는 read-only 계열 상태의 의미입니다.
.. SPDX-License-Identifier: GPL-2.0
================
uevents and GFS2
================
During the lifetime of a GFS2 mount, a number of uevents are generated.
This document explains what the events are and what they are used
for (by gfs_controld in gfs2-utils).
A list of GFS2 uevents
======================
1. ADD
------
The ADD event occurs at mount time. It will always be the first
uevent generated by the newly created filesystem. If the mount
is successful, an ONLINE uevent will follow. If it is not successful
then a REMOVE uevent will follow.
The ADD uevent has two environment variables: SPECTATOR=[0|1]
and RDONLY=[0|1] that specify the spectator status (a read-only mount
with no journal assigned), and read-only (with journal assigned) status
of the filesystem respectively.
2. ONLINE
---------
The ONLINE uevent is generated after a successful mount or remount. It
has the same environment variables as the ADD uevent. The ONLINE
uevent, along with the two environment variables for spectator and
RDONLY are a relatively recent addition (2.6.32-rc+) and will not
be generated by older kernels.
CHANGE·OFFLINE·REMOVE와 호환성
36-77`CHANGE` uevent는 두 곳에서 사용됩니다. 첫 번째 용도는 cluster의 첫 node가 filesystem mount에 성공했음을 `FIRSTMOUNT=Done`으로 보고하는 것입니다.
`gfs_controld`는 이 값을 다른 cluster node도 해당 filesystem을 mount해도 된다는 signal로 사용합니다. 따라서 최초 mount 완료가 나머지 node의 mount 진행을 여는 동기화 지점이 됩니다.
두 번째 `CHANGE` 용도는 filesystem journal 하나의 recovery 완료를 알리는 것입니다. `JID=`는 방금 복구한 journal id를 지정하고, `RECOVERY=[Done|Failed]`는 작업의 성공 여부를 나타냅니다.
journal recovery event는 복구된 journal마다 하나씩 생성됩니다. 초기 mount 과정에서 수행한 recovery뿐 아니라 `gfs_controld`가 `/sys/fs/gfs2/<fsname>/lock_module/recovery` 파일을 통해 특정 journal recovery를 요청한 경우에도 발생합니다.
초기 버전 `gfs_controld`는 environment variable을 확인해 상태를 구분하지 않은 채 `CHANGE` event 자체만 사용했습니다. 이 때문에 `CHANGE`에 새로운 기능을 추가하면 오래된 user tool이 event를 잘못 해석하여 cluster를 망가뜨릴 위험이 있습니다.
이 하위 호환성 제약 때문에 성공한 mount나 remount를 알리는 새 기능에는 `CHANGE`를 확장하지 않고 별도의 `ONLINE` uevent를 사용했습니다.
`OFFLINE`은 filesystem error 때문에만 생성되며 GFS2의 `withdraw` mechanism 일부로 사용됩니다. 현재 event에는 어떤 error가 발생했는지 알려 주는 정보가 없으며, 원문은 이를 수정해야 할 한계로 지적합니다.
`REMOVE`는 mount가 실패한 끝이나 filesystem을 unmount한 끝에 생성됩니다. 같은 filesystem의 모든 `REMOVE`보다 앞에는 최소한 하나의 `ADD`가 존재합니다.
다른 GFS2 uevent와 달리 `REMOVE`는 GFS2가 직접 구성하는 것이 아니라 kernel의 kobject subsystem이 자동으로 생성합니다.
event의 발생 조건과 event 전용 environment variable을 정리합니다.
CHANGE의 두 의미는 environment variable로 구분됩니다.
3. CHANGE
---------
The CHANGE uevent is used in two places. One is when reporting the
successful mount of the filesystem by the first node (FIRSTMOUNT=Done).
This is used as a signal by gfs_controld that it is then ok for other
nodes in the cluster to mount the filesystem.
The other CHANGE uevent is used to inform of the completion
of journal recovery for one of the filesystems journals. It has
two environment variables, JID= which specifies the journal id which
has just been recovered, and RECOVERY=[Done|Failed] to indicate the
success (or otherwise) of the operation. These uevents are generated
for every journal recovered, whether it is during the initial mount
process or as the result of gfs_controld requesting a specific journal
recovery via the /sys/fs/gfs2/<fsname>/lock_module/recovery file.
Because the CHANGE uevent was used (in early versions of gfs_controld)
without checking the environment variables to discover the state, we
cannot add any more functions to it without running the risk of
someone using an older version of the user tools and breaking their
cluster. For this reason the ONLINE uevent was used when adding a new
uevent for a successful mount or remount.
4. OFFLINE
----------
The OFFLINE uevent is only generated due to filesystem errors and is used
as part of the "withdraw" mechanism. Currently this doesn't give any
information about what the error is, which is something that needs to
be fixed.
5. REMOVE
---------
The REMOVE uevent is generated at the end of an unsuccessful mount
or at the end of a umount of the filesystem. All REMOVE uevents will
have been preceded by at least an ADD uevent for the same filesystem,
and unlike the other uevents is generated automatically by the kernel's
kobject subsystem.
모든 GFS2 uevent의 공통 환경변수
78-112모든 GFS2 uevent에는 filesystem과 cluster lock 구성을 식별하는 공통 environment variable이 포함될 수 있습니다.
`LOCKTABLE=`은 mount command line의 `locktable=` option 또는 `fstab`에서 전달한 문자열입니다. filesystem label로 사용되는 동시에 `lock_dlm` mount가 cluster에 참여하는 데 필요한 정보를 제공합니다.
`LOCKPROTO=`도 mount command line이나 `fstab` 설정에서 정해지는 문자열입니다. 현재 값은 `lock_nolock` 또는 `lock_dlm` 중 하나이며, 원문은 미래에 다른 lock manager가 지원될 수 있다고 설명합니다.
`JOURNALID=`는 filesystem이 journal을 사용한다면 모든 GFS2 uevent에 numeric journal id를 제공합니다. spectator mount에는 journal이 할당되지 않으므로 이 변수도 제공되지 않습니다.
recovery 완료 `CHANGE`의 `JID=`는 방금 복구한 journal을 가리키는 event 전용 값이고, 공통 `JOURNALID=`는 현재 mount에 할당된 journal을 식별합니다. 이름이 비슷하지만 의미와 범위가 다릅니다.
최근 버전의 `gfs2-utils`에서 `mkfs.gfs2`는 filesystem superblock에 `UUID`를 기록합니다. UUID가 존재하면 해당 filesystem과 관련된 모든 uevent에 `UUID=`가 포함됩니다.
각 변수의 출처와 event 포함 조건입니다.
비슷한 이름의 두 journal 식별자를 혼동하지 않도록 범위를 구분합니다.
Information common to all GFS2 uevents (uevent environment variables)
=====================================================================
1. LOCKTABLE=
--------------
The LOCKTABLE is a string, as supplied on the mount command
line (locktable=) or via fstab. It is used as a filesystem label
as well as providing the information for a lock_dlm mount to be
able to join the cluster.
2. LOCKPROTO=
-------------
The LOCKPROTO is a string, and its value depends on what is set
on the mount command line, or via fstab. It will be either
lock_nolock or lock_dlm. In the future other lock managers
may be supported.
3. JOURNALID=
-------------
If a journal is in use by the filesystem (journals are not
assigned for spectator mounts) then this will give the
numeric journal id in all GFS2 uevents.
4. UUID=
--------
With recent versions of gfs2-utils, mkfs.gfs2 writes a UUID
into the filesystem superblock. If it exists, this will
be included in every uevent relating to the filesystem.
요약·해설
gfs2-uevents.rst:1-112GFS2 uevent는 mount 생명주기, cluster 최초 mount 동기화, journal recovery, filesystem withdraw를 user space의 `gfs_controld`에 전달합니다. event 이름만으로 의미가 완전히 정해지지 않는 `CHANGE`는 반드시 `FIRSTMOUNT`, `JID`, `RECOVERY` 변수를 함께 해석해야 합니다.
운영 도구는 구형 kernel의 `ONLINE` 미지원과 구형 `gfs_controld`의 `CHANGE` 처리 방식도 고려해야 합니다. 공통 변수인 `LOCKTABLE`, `LOCKPROTO`, `JOURNALID`, `UUID`는 event를 올바른 filesystem과 cluster 구성에 연결하는 식별 정보입니다.
mount 시작부터 정상·오류 종료와 recovery 알림까지의 큰 흐름입니다.