import-mmp-chapter-from-wiki-page

   1 ext4: import multi-mount protection chapter from wiki page
   2
   3 From: Darrick J. Wong <darrick.wong@oracle.com>
   4
   5 Import the chapter about multi-mount protection from the on-disk format
   6 wiki page into the kernel documentation.
   7
   8 Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
   9 Signed-off-by: Theodore Ts'o <tytso@mit.edu>
  10 ---
  11  Documentation/filesystems/ext4/ondisk/globals.rst |    1
  12  Documentation/filesystems/ext4/ondisk/mmp.rst     |   77 +++++++++++++++++++++
  13  2 files changed, 78 insertions(+)
  14  create mode 100644 Documentation/filesystems/ext4/ondisk/mmp.rst
  15
  16
  17 diff --git a/Documentation/filesystems/ext4/ondisk/globals.rst b/Documentation/filesystems/ext4/ondisk/globals.rst
  18 index 5891ee137749..fe6e107bf515 100644
  19 --- a/Documentation/filesystems/ext4/ondisk/globals.rst
  20 +++ b/Documentation/filesystems/ext4/ondisk/globals.rst
  21 @@ -9,3 +9,4 @@ have static metadata at fixed locations.
  22  .. include:: super.rst
  23  .. include:: group_descr.rst
  24  .. include:: bitmaps.rst
  25 +.. include:: mmp.rst
  26 diff --git a/Documentation/filesystems/ext4/ondisk/mmp.rst b/Documentation/filesystems/ext4/ondisk/mmp.rst
  27 new file mode 100644
  28 index 000000000000..b7d7a3137f80
  29 --- /dev/null
  30 +++ b/Documentation/filesystems/ext4/ondisk/mmp.rst
  31 @@ -0,0 +1,77 @@
  32 +.. SPDX-License-Identifier: GPL-2.0
  33 +
  34 +Multiple Mount Protection
  35 +-------------------------
  36 +
  37 +Multiple mount protection (MMP) is a feature that protects the
  38 +filesystem against multiple hosts trying to use the filesystem
  39 +simultaneously. When a filesystem is opened (for mounting, or fsck,
  40 +etc.), the MMP code running on the node (call it node A) checks a
  41 +sequence number. If the sequence number is EXT4\_MMP\_SEQ\_CLEAN, the
  42 +open continues. If the sequence number is EXT4\_MMP\_SEQ\_FSCK, then
  43 +fsck is (hopefully) running, and open fails immediately. Otherwise, the
  44 +open code will wait for twice the specified MMP check interval and check
  45 +the sequence number again. If the sequence number has changed, then the
  46 +filesystem is active on another machine and the open fails. If the MMP
  47 +code passes all of those checks, a new MMP sequence number is generated
  48 +and written to the MMP block, and the mount proceeds.
  49 +
  50 +While the filesystem is live, the kernel sets up a timer to re-check the
  51 +MMP block at the specified MMP check interval. To perform the re-check,
  52 +the MMP sequence number is re-read; if it does not match the in-memory
  53 +MMP sequence number, then another node (node B) has mounted the
  54 +filesystem, and node A remounts the filesystem read-only. If the
  55 +sequence numbers match, the sequence number is incremented both in
  56 +memory and on disk, and the re-check is complete.
  57 +
  58 +The hostname and device filename are written into the MMP block whenever
  59 +an open operation succeeds. The MMP code does not use these values; they
  60 +are provided purely for informational purposes.
  61 +
  62 +The checksum is calculated against the FS UUID and the MMP structure.
  63 +The MMP structure (``struct mmp_struct``) is as follows:
  64 +
  65 +.. list-table::
  66 +   :widths: 1 1 1 77
  67 +   :header-rows: 1
  68 +
  69 +   * - Offset
  70 +     - Type
  71 +     - Name
  72 +     - Description
  73 +   * - 0x0
  74 +     - \_\_le32
  75 +     - mmp\_magic
  76 +     - Magic number for MMP, 0x004D4D50 (“MMP”).
  77 +   * - 0x4
  78 +     - \_\_le32
  79 +     - mmp\_seq
  80 +     - Sequence number, updated periodically.
  81 +   * - 0x8
  82 +     - \_\_le64
  83 +     - mmp\_time
  84 +     - Time that the MMP block was last updated.
  85 +   * - 0x10
  86 +     - char[64]
  87 +     - mmp\_nodename
  88 +     - Hostname of the node that opened the filesystem.
  89 +   * - 0x50
  90 +     - char[32]
  91 +     - mmp\_bdevname
  92 +     - Block device name of the filesystem.
  93 +   * - 0x70
  94 +     - \_\_le16
  95 +     - mmp\_check\_interval
  96 +     - The MMP re-check interval, in seconds.
  97 +   * - 0x72
  98 +     - \_\_le16
  99 +     - mmp\_pad1
 100 +     - Zero.
 101 +   * - 0x74
 102 +     - \_\_le32[226]
 103 +     - mmp\_pad2
 104 +     - Zero.
 105 +   * - 0x3FC
 106 +     - \_\_le32
 107 +     - mmp\_checksum
 108 +     - Checksum of the MMP block.
 109
 110