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