0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ================
0004 uevents and GFS2
0005 ================
0006
0007 During the lifetime of a GFS2 mount, a number of uevents are generated.
0008 This document explains what the events are and what they are used
0009 for (by gfs_controld in gfs2-utils).
0010
0011 A list of GFS2 uevents
0012 ======================
0013
0014 1. ADD
0015 ------
0016
0017 The ADD event occurs at mount time. It will always be the first
0018 uevent generated by the newly created filesystem. If the mount
0019 is successful, an ONLINE uevent will follow. If it is not successful
0020 then a REMOVE uevent will follow.
0021
0022 The ADD uevent has two environment variables: SPECTATOR=[0|1]
0023 and RDONLY=[0|1] that specify the spectator status (a read-only mount
0024 with no journal assigned), and read-only (with journal assigned) status
0025 of the filesystem respectively.
0026
0027 2. ONLINE
0028 ---------
0029
0030 The ONLINE uevent is generated after a successful mount or remount. It
0031 has the same environment variables as the ADD uevent. The ONLINE
0032 uevent, along with the two environment variables for spectator and
0033 RDONLY are a relatively recent addition (2.6.32-rc+) and will not
0034 be generated by older kernels.
0035
0036 3. CHANGE
0037 ---------
0038
0039 The CHANGE uevent is used in two places. One is when reporting the
0040 successful mount of the filesystem by the first node (FIRSTMOUNT=Done).
0041 This is used as a signal by gfs_controld that it is then ok for other
0042 nodes in the cluster to mount the filesystem.
0043
0044 The other CHANGE uevent is used to inform of the completion
0045 of journal recovery for one of the filesystems journals. It has
0046 two environment variables, JID= which specifies the journal id which
0047 has just been recovered, and RECOVERY=[Done|Failed] to indicate the
0048 success (or otherwise) of the operation. These uevents are generated
0049 for every journal recovered, whether it is during the initial mount
0050 process or as the result of gfs_controld requesting a specific journal
0051 recovery via the /sys/fs/gfs2/<fsname>/lock_module/recovery file.
0052
0053 Because the CHANGE uevent was used (in early versions of gfs_controld)
0054 without checking the environment variables to discover the state, we
0055 cannot add any more functions to it without running the risk of
0056 someone using an older version of the user tools and breaking their
0057 cluster. For this reason the ONLINE uevent was used when adding a new
0058 uevent for a successful mount or remount.
0059
0060 4. OFFLINE
0061 ----------
0062
0063 The OFFLINE uevent is only generated due to filesystem errors and is used
0064 as part of the "withdraw" mechanism. Currently this doesn't give any
0065 information about what the error is, which is something that needs to
0066 be fixed.
0067
0068 5. REMOVE
0069 ---------
0070
0071 The REMOVE uevent is generated at the end of an unsuccessful mount
0072 or at the end of a umount of the filesystem. All REMOVE uevents will
0073 have been preceded by at least an ADD uevent for the same filesystem,
0074 and unlike the other uevents is generated automatically by the kernel's
0075 kobject subsystem.
0076
0077
0078 Information common to all GFS2 uevents (uevent environment variables)
0079 =====================================================================
0080
0081 1. LOCKTABLE=
0082 --------------
0083
0084 The LOCKTABLE is a string, as supplied on the mount command
0085 line (locktable=) or via fstab. It is used as a filesystem label
0086 as well as providing the information for a lock_dlm mount to be
0087 able to join the cluster.
0088
0089 2. LOCKPROTO=
0090 -------------
0091
0092 The LOCKPROTO is a string, and its value depends on what is set
0093 on the mount command line, or via fstab. It will be either
0094 lock_nolock or lock_dlm. In the future other lock managers
0095 may be supported.
0096
0097 3. JOURNALID=
0098 -------------
0099
0100 If a journal is in use by the filesystem (journals are not
0101 assigned for spectator mounts) then this will give the
0102 numeric journal id in all GFS2 uevents.
0103
0104 4. UUID=
0105 --------
0106
0107 With recent versions of gfs2-utils, mkfs.gfs2 writes a UUID
0108 into the filesystem superblock. If it exists, this will
0109 be included in every uevent relating to the filesystem.
0110
0111
0112
