uevents.rst

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