Commit | Line | Data |
---|---|---|
5b7ac27a MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ================ | |
4 | uevents and GFS2 | |
5 | ================ | |
0aa87445 SW |
6 | |
7 | During the lifetime of a GFS2 mount, a number of uevents are generated. | |
8 | This document explains what the events are and what they are used | |
9 | for (by gfs_controld in gfs2-utils). | |
10 | ||
11 | A list of GFS2 uevents | |
5b7ac27a | 12 | ====================== |
0aa87445 SW |
13 | |
14 | 1. ADD | |
5b7ac27a | 15 | ------ |
0aa87445 SW |
16 | |
17 | The ADD event occurs at mount time. It will always be the first | |
18 | uevent generated by the newly created filesystem. If the mount | |
19 | is successful, an ONLINE uevent will follow. If it is not successful | |
20 | then a REMOVE uevent will follow. | |
21 | ||
22 | The ADD uevent has two environment variables: SPECTATOR=[0|1] | |
23 | and RDONLY=[0|1] that specify the spectator status (a read-only mount | |
24 | with no journal assigned), and read-only (with journal assigned) status | |
25 | of the filesystem respectively. | |
26 | ||
27 | 2. ONLINE | |
5b7ac27a | 28 | --------- |
0aa87445 SW |
29 | |
30 | The ONLINE uevent is generated after a successful mount or remount. It | |
31 | has the same environment variables as the ADD uevent. The ONLINE | |
32 | uevent, along with the two environment variables for spectator and | |
33 | RDONLY are a relatively recent addition (2.6.32-rc+) and will not | |
34 | be generated by older kernels. | |
35 | ||
36 | 3. CHANGE | |
5b7ac27a | 37 | --------- |
0aa87445 SW |
38 | |
39 | The CHANGE uevent is used in two places. One is when reporting the | |
40 | successful mount of the filesystem by the first node (FIRSTMOUNT=Done). | |
41 | This is used as a signal by gfs_controld that it is then ok for other | |
42 | nodes in the cluster to mount the filesystem. | |
43 | ||
44 | The other CHANGE uevent is used to inform of the completion | |
45 | of journal recovery for one of the filesystems journals. It has | |
46 | two environment variables, JID= which specifies the journal id which | |
47 | has just been recovered, and RECOVERY=[Done|Failed] to indicate the | |
48 | success (or otherwise) of the operation. These uevents are generated | |
49 | for every journal recovered, whether it is during the initial mount | |
50 | process or as the result of gfs_controld requesting a specific journal | |
51 | recovery via the /sys/fs/gfs2/<fsname>/lock_module/recovery file. | |
52 | ||
53 | Because the CHANGE uevent was used (in early versions of gfs_controld) | |
54 | without checking the environment variables to discover the state, we | |
55 | cannot add any more functions to it without running the risk of | |
56 | someone using an older version of the user tools and breaking their | |
57 | cluster. For this reason the ONLINE uevent was used when adding a new | |
58 | uevent for a successful mount or remount. | |
59 | ||
60 | 4. OFFLINE | |
5b7ac27a | 61 | ---------- |
0aa87445 SW |
62 | |
63 | The OFFLINE uevent is only generated due to filesystem errors and is used | |
64 | as part of the "withdraw" mechanism. Currently this doesn't give any | |
65 | information about what the error is, which is something that needs to | |
66 | be fixed. | |
67 | ||
68 | 5. REMOVE | |
5b7ac27a | 69 | --------- |
0aa87445 SW |
70 | |
71 | The REMOVE uevent is generated at the end of an unsuccessful mount | |
72 | or at the end of a umount of the filesystem. All REMOVE uevents will | |
40e47125 | 73 | have been preceded by at least an ADD uevent for the same filesystem, |
0aa87445 SW |
74 | and unlike the other uevents is generated automatically by the kernel's |
75 | kobject subsystem. | |
76 | ||
77 | ||
78 | Information common to all GFS2 uevents (uevent environment variables) | |
5b7ac27a | 79 | ===================================================================== |
0aa87445 SW |
80 | |
81 | 1. LOCKTABLE= | |
5b7ac27a | 82 | -------------- |
0aa87445 SW |
83 | |
84 | The LOCKTABLE is a string, as supplied on the mount command | |
85 | line (locktable=) or via fstab. It is used as a filesystem label | |
86 | as well as providing the information for a lock_dlm mount to be | |
87 | able to join the cluster. | |
88 | ||
89 | 2. LOCKPROTO= | |
5b7ac27a | 90 | ------------- |
0aa87445 SW |
91 | |
92 | The LOCKPROTO is a string, and its value depends on what is set | |
93 | on the mount command line, or via fstab. It will be either | |
94 | lock_nolock or lock_dlm. In the future other lock managers | |
95 | may be supported. | |
96 | ||
97 | 3. JOURNALID= | |
5b7ac27a | 98 | ------------- |
0aa87445 SW |
99 | |
100 | If a journal is in use by the filesystem (journals are not | |
101 | assigned for spectator mounts) then this will give the | |
102 | numeric journal id in all GFS2 uevents. | |
103 | ||
104 | 4. UUID= | |
5b7ac27a | 105 | -------- |
0aa87445 SW |
106 | |
107 | With recent versions of gfs2-utils, mkfs.gfs2 writes a UUID | |
108 | into the filesystem superblock. If it exists, this will | |
109 | be included in every uevent relating to the filesystem. | |
110 | ||
111 | ||
112 |