Whamcloud - gitweb
9245420ad3a05c8d8fff208fbc26b1b12ebc4f66
[fs/lustre-release.git] / 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 checks for a large
7 variety of inconsistencies between meta data targets (MDTs) and object storage
8 targets (OSTs) and provides automatic correction where possible.
9
10 LFSCK does not check consistency of the on-disk format and assumes that it is
11 consistent. For ldiskfs, e2fsck from e2fsprogs should be used to ensure the on
12 disk format is consistent. ZFS is designed to always have a valid on-disk
13 structure and as a result, no 'fsck' is necessary.
14
15
16 Quick usage instructions
17 ===============================================
18
19 - start a standard scan
20
21 LFSCK only runs on an MDS, and starts scanning automatically if an
22 inconsistency is detected when the MDT service is started. The scan can be
23 started manually on a running MDT using the command:
24
25 # lctl lfsck_start --type namespace --type layout -M testfs-MDT0000
26
27 - reviewing the status of lfsck
28
29 lfsck only provides status from a MDS.
30
31 # lctl get_param -n mdd.lustre-MDT0000.lfsck_namespace
32
33 - stop a lfsck scan
34
35 # lctl lfsck_stop -M lustre-MDT0000
36
37
38 Features
39 ===============================================
40
41 * online scanning.
42 * control of scanning rate.
43 * automatic checkpoint recovery of an interrupted scan.
44 * reconstruciton of the FID-to-inode mapping after a file level restore or 1.8
45   upgrade
46 * fixing FID-in-Dirent name entry to be consistent with the FID in the inode
47   LMA.
48 * detection and repair including:
49   * MDT-OST inconsistencies, including:
50   * dangling references.
51   * unreferenced OST objects.
52   * mismatched references.
53   * multiple references.
54 * monitoring using proc and lctl interfaces.
55
56
57 /proc entries
58 ===============================================
59
60 Information about lfsck can be found in
61 /proc/fs/lustre/mdd/<fsname>-<mdt>/lfsck_{namespace,layout}
62
63
64 LFSCK master slave design
65 ===============================================
66
67 The LFSCK master engine resides on the MDT, and is implemented as a kernel
68 thread in the LFSCK layer. The master engine is responsible for scanning on the
69 MDT and also controls slave engines on OSTs. Scanning on both MDTs and OSTs
70 occurs in two stages. These stages are firstly consistency check and repair and
71 secondly orphan identification and processing.
72
73 1. The master engine is started either by the user space command or an
74 excessive number of MDT-OST inconsistency events are detected. On starting, the
75 master engine sends RPCs to related OSTs to start the slave engines.
76
77 2. The master engine on the MDS scans the MDT device using namespace iteration
78 (described below). For each striped file, it calls the registered LFSCK process
79 handlers to perform the relevant system consistency check/repair, which is are
80 enumerated in the 'features' section. All objects on OSTs that are never
81 referenced during this scan (because, for example, they are orphans) are
82 recorded in an OST orphan object index on each OST.
83
84 3. After the MDT completes first-stage system scanning, the master engine sends
85 RPCs to OSTs that have relations to the MDT, to make the OST begin scanning.
86 The master engine waits for the slave engines to complete the first-stage
87 system scan and is signaled in turn by an RPC from each OST.
88
89
90 The LFSCK slave engine resides on each OST, and is implemented as a kernel
91 thread in the LFSCK layer. This kernel thread drives the first-stage system
92 scan on the OST.
93
94 1. When the slave engine is triggered by the RPC from the master engine in the
95 first phase, the OST scans the local OST deviceto generate the in-memory OST
96 orphan object index.
97
98 2. When the first-stage system scan (for both MDTs and OSTs) is complete a list
99 of non-referenced OST-objects is available. Only objects that are not accessed
100 during the first stage scan are regarded as potential orphans.
101
102 3. In the second stage, the OSTs scan to resolve orphan objects in the file
103 system. The OST orphan object index is used as input to the second stage. For
104 each item in the index, the presence of a parent MDT object is verified. Orphan
105 objects will either be relinked to an existing file if found - or moved into a
106 new file in .lustre/lost+found.
107
108 If multiple MDTs are present, MDTs will check/repair MDT-OST consistency in
109 parallel. To avoid scans of the OST device the slave engine will not begin
110 second-stage system scans until all the master engines complete the first-stage
111 system scan. For each OST there is a single OST orphan object index, regardless
112 of how many MDTs are in the MDT-OST consistency check/repair.
113
114
115 Object traversal design reference
116 ===============================================
117
118 Objects are traversed by LFSCK with two methods. inode traversal and namespace
119 traversal. For all types, the OST iterates through objects with inode
120 traversal. The MDT will choose the iteration appropriate to the scaning type
121 requested. Layout uses inode traversal, namespace use namespace traversal.
122
123 * inode traversal
124
125 Two kernel threads are employed to maximize the performance of this operation.
126 One Object Storage Device (OSD) thread performs the inode table iteration,
127 which scans MDT inode table and submits inode read requests asynchronously to
128 drive disk I/O efficiently.  The second thread is the OI Scrub thread which
129 searches the OI table and updates related mapping entries. The two threads run
130 concurrently and iterate inodes in a pipeline.
131
132 The Object Storage Device (OSD) is the abstract layer above a concrete back-end
133 file system (i.e. ext4, ZFS, Btrfs, etc.). Each OSD implementation differs
134 internally to support concrete file systems. In order to support OI Scrub the
135 inode iterator is presented via the OSD API as a virtual index that contains
136 all the inodes in the file system. Common interface calls are created to
137 implement inode table based iteration to enable support for additional concrete
138 file system in the future.
139
140 * namespace traversal
141
142 In addition to inode traversal, there are directory based items that
143 need scanning for namespace consistency. For example, FID-in-Dirent and LinkEA
144 are directory based features.
145
146 A naive approach to namespace traversal would be to descend recursively from
147 the file system root. However, this approach will typically generate random IO,
148 which for performance reasons should be minimized. In addition, one must
149 consider operations (i.e. rename) taking place within a directory that is
150 currently being scanned. For these reasons a hybrid approach to scanning is
151 employed.
152
153 1. LFSCK begins inode traversal.
154
155 2. If a directory is discovered then namespace traversal begins. LFSCK does not
156 descend into sub-directories. LFSCK ignores rename operations during the
157 directory traversal because the subsequent inode traversal will guarantee
158 processing of renamed objects. Reading directory blocks is a small fraction of
159 the data needed for the inodes they reference. In addition, entries in the
160 directory are typically allocated following the directory inode on the disk so
161 for many directories the children inodes will already be available because of
162 pre-fetch.
163
164 3. Process each entry in the directory checking the FID-in-Dirent and the FID
165 in the object LMA are consistent. Repair if not. Check also that the linkEA
166 points back to the parent object. Check also that '.' and '..' entries are
167 consistent.
168
169 4. Once all directory entries are exhausted, return to inode traversal.
170
171
172 References
173 ===============================================
174
175 source code:       file:/lustre/lfsck/
176
177 operations manual: http://build.whamcloud.com/job/lustre-manual/lastSuccessfulBuild/artifact/lustre_manual.xhtml#dbdoclet.lfsckadmin
178
179 useful links:      http://insidehpc.com/2013/05/02/video-lfsck-online-lustre-file-system-checker/
180                    http://www.opensfs.org/wp-content/uploads/2013/04/Zhuravlev_LFSCK.pdf
181
182
183 Glossary of terms
184 ===============================================
185
186 OSD - Object storage device. A generic term for a storage device with an
187   interface that extends beyond a block-orientated device interface.
188
189 OI - Object Index. A table that maps FIDs to inodes. This table must be
190   regenerated if a file level restore is performed as inodes will change.
191
192 FID - File IDentifier. A Lustre file system identifies every file and object
193   with a unique 128-bit ID.
194
195 FID-in-Dirent - FID in Directory Entry. To enhance the performance of readdir,
196   the FID (and name) of a file are recorded in the current directory entry.
197
198 LMA - Lustre Metadata Attributes. A record of Lustre specific attributes, for
199   example HSM state.
200
201 linkEA - Link Extended Attributes. When a file is created or hard-linked the
202   parent directory name and FID are recorded as extended attributes to the file.
203