Documentation/lfsck.txt

   1
   2 LFSCK: an online file system checker for Lustre
   3 ===============================================
   4
   5 LFSCK is an online tool to scan, check and repair a Lustre file system that can
   6 be used with a file system that is mounted and in use. It contains three main
   7 LFSCK components: OI Scrub (primarily of use for ldiskfs-based backend), Layout
   8 LFSCK, and Namespace LFSCK. Each component identifies different types of Lustre
   9 inconsistencies.
  10
  11 LFSCK does not verify the on-disk format and assumes that it is consistent. For
  12 ldiskfs-based backend, e2fsck from e2fsprogs should be used to ensure the on
  13 disk format is consistent. ZFS is designed to always have a valid on-disk
  14 structure and as a result, no 'fsck' is necessary.
  15
  16 * OI Scrub
  17
  18 OI scrub is of primary use for ldiskfs-based targets. It maintains the ldiskfs
  19 special OI mapping consistency, reconstructs the OI mapping after the target
  20 is restored from file-level backup, and upgrades (if necessary) the OI mapping
  21 when target (MDT/OST) is upgraded from a previous release.
  22
  23 * Layout LFSCK
  24
  25 Layout LFSCK is concerned with consistency between metadata targets (MDTs) and
  26 object storage targets (OSTs). It automatically corrects inconsistencies where
  27 possible.
  28
  29 * Namespace LFSCK
  30
  31 Namespace LFSCK is concerned with consistency across the Lustre namespace.
  32 Namespace LFSCK works transparently across single and multiple MDTs.
  33
  34 Quick usage instructions
  35 ===============================================
  36
  37 * Start LFSCK
  38
  39 If you only want OI scrub on a given MDT or OST, use this command on the given
  40 MDT or OST:
  41 # lctl lfsck_start -t scrub -M ${FSNAME}-${TARGETNAME}
  42
  43 (FSNAME: the specified file system name created during format, e.g. "testfs".
  44  TARGETNAME: the target name in the system, e.g. "MDT0000" or "OST0001".)
  45
  46 If you want Layout LFSCK or Namespace LFSCK on a given MDT(s) and OST(s), use
  47 this command on the specified MDT:
  48
  49 # lctl lfsck_start -t namespace -M ${FSNAME}-${MDTNAME}
  50 or
  51 # lctl lfsck_start -t layout -M ${FSNAME}-${MDTNAME}
  52
  53 (MDTNAME: the MDT name in the system, e.g. "MDT0000", "MDT0001".)
  54
  55 You can trigger multiple LFSCK components via single LFSCK command:
  56 # lctl lfsck_start -t namespace -t layout -M ${FSNAME}-${MDTNAME}
  57
  58 For more usage, please run:
  59 # lctl lfsck_start -h
  60
  61 * review the status of LFSCK
  62
  63 Each LFSCK component has its own status interface on a given target.
  64 For example, the Namespace LFSCK status on the MDT:
  65 # lctl get_param -n mdd.${FSNAME}-${MDTNAME}.lfsck_namespace
  66
  67 Or the Layout LFSCK status on the OST:
  68 # lctl get_param -n obdfilter.${FSNAME}-${OSTNAME}.lfsck_layout
  69 NOTE: Layout LFSCK also works on a OST.
  70
  71 (OSTNAME: the OST name in the system, e.g. "OST0000", "OST0001".)
  72
  73 Or the OI Scrub status on the MDT/OST:
  74 # lctl get_param -n osd-ldiskfs.${FSNAME}-${TARGETNAME}.oi_scrub
  75
  76 * stop the LFSCK
  77
  78 Run the command on the given MDT/OST:
  79 # lctl lfsck_stop -M ${FSNAME}-${MDTNAME}
  80
  81 To stop all LFSCK across the system:
  82 # lctl lfsck_stop -M ${FSNAME} -A
  83
  84
  85 Features
  86 ===============================================
  87
  88 * online scanning.
  89 * control of scanning rate.
  90 * automatic checkpoint recovery of an interrupted scan.
  91 * monitoring using proc and lctl interfaces.
  92 * maintain OI mapping for ldiskfs-based backend.
  93   * reconstruction of the OI mapping after the target (MDT/OST) restored from
  94     file-level backup.
  95   * generate OI mapping for the MDT upgraded from 1.8.
  96   * rebuild OI mapping if some of them lost or crashed.
  97 * check and repair kinds of namespace related inconsistent issues:
  98   * the FID-in-dirent should be consistent with the FID-in-LMA.
  99   * the linkEA should be consistent with related name entries.
 100   * Dangling name entry: the name entry exists, but related MDT-object does
 101     not exist.
 102   * Orphan MDT-object: the MDT-object exists, but there is no name entry to
 103     reference it.
 104   * Multiple-referenced name entry: more than one MDT-objects point back to
 105     the same name entry, but the name entry only references one of them.
 106   * Unmatched name entry and MDT-object pairs: the name entry references the
 107     MDT-object that has no linkEA for back-reference or points back to another
 108     name entry that does not exist or does not reference the MDT-object.
 109   * Unmatched object types: the file type in the name entry does not match the
 110     type that is claimed by the MDT-object.
 111   * Invalid nlink count: the MDT-object's nlink count does not match the number
 112     of name entries that reference such MDT-object.
 113   * Invalid name hash for striped directory: the name hash for the name entry
 114     on a shard of a striped directory does not match the index stored in the
 115     shard's LMV xattr.
 116 * verify layout consistency between MDT and OST:
 117   * MDT-object with dangling reference: the MDT-object1 claims that the
 118     OST-object1 is its child stripe, but on the OST, the OST-object1 does not
 119     exist, or it is not materialized (so does not recognize the MDT-object1 as
 120     its parent).
 121   * Unmatched referenced MDT-object/OST-object pairs: the MDT-object1 claims
 122     that the OST-object1 is its child stripe, but the OST-object1 claims that
 123     its parent is the MDT-object2 rather than the MDT-object1. On the MDT,
 124     the MDT-object2 does not exist, or not recognize the OST-object1 as its
 125     child stripe. An additional case exists where the child index stored in
 126     the parent layout information does not match the index information stored
 127     in the child itself.
 128   * Multiple referenced OST-object: the MDT-object1 claims that the OST-object1
 129     is its child stripe, but the OST-object1 claims that its parent is the
 130     MDT-object2 rather than the MDT-object1. On the other hand, the MDT-object2
 131     recognizes the OST-object1 as its child stripe.
 132   * Unreferenced (orphan) OST-object: the OST-object1 claims that the
 133     MDT-object1 is its parent, but on the MDT, the MDT-object1 does not exist,
 134     or it does not recognize the OST-object1 as its child.
 135
 136
 137 /proc entries
 138 ===============================================
 139
 140 Information about LFSCK can be found in:
 141 /proc/fs/lustre/mdd/${FSNAME}-${MDTNAME}/lfsck_{namespace,layout}
 142 /proc/fs/lustre/obdfilter/${FSNAME}-${OSTNAME}/lfsck_layout
 143 /proc/fs/lustre/osd-ldiskfs/${FSNAME}-${TARGETNAME}/oi_scrub
 144
 145
 146 LFSCK master slave design
 147 ===============================================
 148
 149 * master engine
 150
 151 The LFSCK master engine resides on each MDT, and is implemented as a kernel
 152 thread in the LFSCK layer. The master engine is responsible for scanning on the
 153 MDTs and also controls slave engines on OSTs. Scanning on both MDTs and OSTs
 154 occurs in two stages. First-stage scanning will identify and resolve most of
 155 inconsistencies. In the second stage, information from the first stage will be
 156 used to resolve a remaining set of inconsistencies that had uncertain
 157 resolution after only one scan.
 158
 159
 160 1. The master engine is started either by the user space command or an
 161 excessive number of inconsistency events are detected (defined by
 162 osd-ldiskfs.<fsname>-<targetname>.full_scrub_threshold_rate). On starting, the
 163 master engine sends RPCs to other MDTs (when necessary) to start other master
 164 engines and to related OSTs to start the slave engines.
 165
 166 2. The master engine on the MDS scans the MDT device using namespace iteration
 167 (described below). For each striped file, it calls the registered LFSCK process
 168 handlers to perform the relevant system consistency checks/repairs, which are
 169 enumerated in the 'features' section. All objects on OSTs that are never
 170 referenced during this scan (because, for example, they are orphans) are
 171 recorded in an OST orphan object index on each OST.
 172
 173 3. After the MDT completes first-stage system scanning, the master engine sends
 174 RPCs to related LFSCK engines on other targets to notify that the first-stage
 175 scanning is complete on this MDT. The MDT waits until related targets have
 176 completed the first-stage scanning. At this point, the first stage scanning is
 177 complete and the second-stage scanning begins.
 178
 179 * slave engine
 180
 181 The LFSCK slave engine resides on each OST and is implemented as a kernel
 182 thread in the LFSCK layer. This kernel thread drives the first-stage system
 183 scan on the OST.
 184
 185 1. When the slave engine is triggered by the RPC from the master engine in the
 186 first-stage scanning, the OST scans the local OST device to generate the
 187 in-memory OST orphan object index.
 188
 189 2. When the first-stage scanning (for both MDTs and OSTs) is complete a list of
 190 non-referenced OST-objects has been accumulated. Only objects that are not
 191 accessed during the first stage scan are regarded as potential orphans.
 192
 193 3. In the second-stage scanning, the OSTs work to resolve orphan objects in the
 194 file system. The OST orphan object index is used as input to the second stage.
 195 For each item in the index, the presence of a parent MDT object is verified.
 196 Orphan objects will either be relinked to an existing file if found - or moved
 197 into a new file in .lustre/lost+found.
 198
 199 If multiple MDTs are present, MDTs will check/repair MDT-OST consistency in
 200 parallel. To avoid redundant scans of the OST device the slave engine will not
 201 begin second-stage system scans until all the master engines complete the
 202 first-stage system scan. For each OST there is a single OST orphan object
 203 index, regardless of how many MDTs are in the MDT-OST consistency check/repair.
 204
 205
 206 Object traversal design reference
 207 ===============================================
 208
 209 Objects are traversed by LFSCK with two methods: object-table based iteration
 210 and namespace based directory traversal.
 211
 212 * object-table based iteration
 213
 214 The Object Storage Device (OSD) is the abstract layer above a concrete backend
 215 file system (i.e. ldiskfs, ZFS, Btrfs, etc.). Each OSD implementation differs
 216 internally to support concrete file systems. The object-table based iteration
 217 is implemented inside the OSD. It uses the backend special efficient scanning
 218 method, such as linear scanning for ldiskfs backend, to scan the local device.
 219 Such iteration is presented via the OSD API as a virtual index that contains
 220 all the objects that reside on this target.
 221
 222 * namespace based directory traversal
 223
 224 In addition to object-table based iteration, there are directory based items
 225 that need scanning for namespace consistency. For example, FID-in-dirent and
 226 LinkEA are directory based features.
 227
 228 A naive approach to namespace traversal would be to descend recursively from
 229 the file system root. However, this approach will typically generate random IO,
 230 which for performance reasons should be minimized. In addition, one must
 231 consider operations (i.e. rename) taking place within a directory that is
 232 currently being scanned. For these reasons a hybrid approach to scanning is
 233 employed.
 234
 235 1. LFSCK begins object-table based iteration.
 236
 237 2. If a directory is discovered then namespace traversal begins. LFSCK does not
 238 descend into sub-directories. LFSCK ignores rename operations during the
 239 directory traversal because the subsequent object-table based iteration will
 240 guarantee processing of renamed objects. Reading directory blocks is a small
 241 fraction of the data needed for the objects they reference. In addition, entries
 242 in the directory are typically allocated following the directory object on the
 243 disk so for many directories the children objects will already be available
 244 because of pre-fetch.
 245
 246 3. Process each entry in the directory checking the FID-in-dirent and the FID
 247 in the object LMA are consistent. Repair if not. Check also that the linkEA
 248 points back to the parent object. Check also that '.' and '..' entries are
 249 consistent.
 250
 251 4. Once all directory entries are exhausted, return to object-table based
 252 iteration.
 253
 254
 255 References
 256 ===============================================
 257
 258 source code:       file:/lustre/lfsck/
 259
 260 operations manual: https://build.hpdd.intel.com/job/lustre-manual/lastSuccessfulBuild/artifact/lustre_manual.xhtml#dbdoclet.lfsckadmin
 261
 262 useful links:      http://insidehpc.com/2013/05/02/video-lfsck-online-lustre-file-system-checker/
 263                    http://www.opensfs.org/wp-content/uploads/2013/04/Zhuravlev_LFSCK.pdf
 264
 265
 266 Glossary of terms
 267 ===============================================
 268
 269 FID - File IDentifier. A Lustre file system identifies every file and object
 270   with a unique 128-bit ID.
 271
 272 FID-in-dirent - FID in Directory Entry. To enhance the performance of readdir,
 273   the FID of a file is recorded in its directory name entry.
 274
 275 linkEA - Link Extended Attributes. When a file is created or hard-linked the
 276   parent directory name and FID are recorded as extended attributes to the file.
 277
 278 LMA - Lustre Metadata Attributes. A record of Lustre specific attributes, for
 279   example HSM state, self-FID, and so on.
 280
 281 OI - Object Index. A table that maps FIDs to inodes. On ldiskfs-based targets,
 282   this table must be regenerated if a file level restore is performed as inodes
 283   will change.
 284
 285 OSD - Object storage device. A generic term for a storage device with an
 286   interface that extends beyond a block-oriented device interface.