Debian Codegraph @

upstream/debian-unstable/man8/xfs_repair.8

raw
1 .TH xfs_repair 8
2 .SH NAME
3 xfs_repair \- repair an XFS filesystem
4 .SH SYNOPSIS
5 .B xfs_repair
6 [
7 .B \-dfLPv
8 ] [
9 .BR \-n " | " -e
10 ] [
11 .B \-m
12 .I maxmem
13 ] [
14 .BI \-c " subopt" = value
15 ] [
16 .B \-o
17 .I subopt\c
18 [\c
19 .B =\c
20 .IR value ]
21 ] [
22 .B \-t
23 .I interval
24 ] [
25 .B \-l
26 .I logdev
27 ] [
28 .B \-r
29 .I rtdev
30 ]
31 .I device
32 .br
33 .B xfs_repair \-V
34 .SH DESCRIPTION
35 .B xfs_repair
36 repairs corrupt or damaged XFS filesystems
37 (see
38 .BR xfs (5)).
39 The filesystem is specified using the
40 .I device
41 argument which should be the device name of the disk partition or
42 volume containing the filesystem. If given the name of a block device,
43 .B xfs_repair
44 will attempt to find the raw device associated
45 with the specified block device and will use the raw device instead.
46 .PP
47 Regardless, the filesystem to be repaired
48 must be unmounted,
49 otherwise, the resulting filesystem may be inconsistent or corrupt.
50 .SH OPTIONS
51 .TP
52 .B \-f
53 Specifies that the filesystem image to be processed is stored in a
54 regular file at
55 .I device
56 (see the
57 .B mkfs.xfs \-d
58 .I file
59 option). This might happen if an image copy
60 of a filesystem has been copied or written into an ordinary file.
61 This option implies that any external log or realtime section
62 is also in an ordinary file.
63 .TP
64 .B \-L
65 Force Log Zeroing.
66 Forces
67 .B xfs_repair
68 to zero the log even if it is dirty (contains metadata changes).
69 When using this option the filesystem will likely appear to be corrupt,
70 and can cause the loss of user files and/or data. See the
71 .B "DIRTY LOGS"
72 section for more information.
73 .TP
74 .BI \-l " logdev"
75 Specifies the device special file where the filesystem's external
76 log resides. Only for those filesystems which use an external log.
77 See the
78 .B mkfs.xfs \-l
79 option, and refer to
80 .BR xfs (5)
81 for a detailed description of the XFS log.
82 .TP
83 .BI \-r " rtdev"
84 Specifies the device special file where the filesystem's realtime
85 section resides. Only for those filesystems which use a realtime section.
86 See the
87 .B mkfs.xfs \-r
88 option, and refer to
89 .BR xfs (5)
90 for a detailed description of the XFS realtime section.
91 .TP
92 .B \-n
93 No modify mode. Specifies that
94 .B xfs_repair
95 should not modify the filesystem but should only scan the
96 filesystem and indicate what repairs would have been made. This option cannot
97 be used together with
98 .BR \-e .
99 .TP
100 .B \-P
101 Disable prefetching of inode and directory blocks. Use this option if
102 you find
103 .B xfs_repair
104 gets stuck and stops proceeding. Interrupting a stuck
105 .B xfs_repair
106 is safe.
107 .TP
108 .BI \-m " maxmem"
109 Specifies the approximate maximum amount of memory, in megabytes, to use for
110 .BR xfs_repair .
111 .B xfs_repair
112 has its own internal block cache which will scale out up to the lesser of the
113 process's virtual address limit or about 75% of the system's physical RAM.
114 This option overrides these limits.
115 .IP
116 .B NOTE:
117 These memory limits are only approximate and may use more than the specified
118 limit.
119 .TP
120 .BI \-c " subopt" = value
121 Change filesystem parameters. Refer to
122 .BR xfs_admin (8)
123 for information on changing filesystem parameters.
124 .HP
125 .B \-o
126 .I subopt\c
127 [\c
128 .B =\c
129 .IR value ]
130 .br
131 Override what the program might conclude about the filesystem
132 if left to its own devices.
133 .IP
134 The
135 .IR subopt ions
136 supported are:
137 .RS 1.0i
138 .TP
139 .BI bhash= bhashsize
140 overrides the default buffer cache hash size. The total number of
141 buffer cache entries are limited to 8 times this amount. The default
142 size is set to use up the remainder of 75% of the system's physical
143 RAM size.
144 .TP
145 .BI ag_stride= ags_per_concat_unit
146 This creates additional processing threads to parallel process
147 AGs that span multiple concat units. This can significantly
148 reduce repair times on concat based filesystems.
149 .TP
150 .BI force_geometry
151 Check the filesystem even if geometry information could not be validated.
152 Geometry information can not be validated if only a single allocation
153 group exists and thus we do not have a backup superblock available, or
154 if there are two allocation groups and the two superblocks do not
155 agree on the filesystem geometry. Only use this option if you validated
156 the geometry yourself and know what you are doing. If In doubt run
157 in no modify mode first.
158 .TP
159 .BI noquota
160 Don't validate quota counters at all.
161 Quotacheck will be run during the next mount to recalculate all values.
162 .RE
163 .TP
164 .B \-t " interval"
165 Modify reporting interval, specified in seconds. During long runs
166 .B xfs_repair
167 outputs its progress every 15 minutes. Reporting is only activated when
168 ag_stride is enabled.
169 .TP
170 .B \-v
171 Verbose output. May be specified multiple times to increase verbosity.
172 .TP
173 .B \-d
174 Repair dangerously. Allow
175 .B xfs_repair
176 to repair an XFS filesystem mounted read only. This is typically done
177 on a root filesystem from single user mode, immediately followed by a reboot.
178 .TP
179 .B \-e
180 If any metadata corruption was repaired, the status returned is 4 instead of the
181 usual 0. This option cannot be used together with
182 .BR \-n .
183 .TP
184 .B \-V
185 Prints the version number and exits.
186 .SS Checks Performed
187 The correctness of the crc32c checksum implementation will be tested
188 before examining the filesystem.
189 If the test fails, the program will abort.
190
191 Inconsistencies corrected include the following:
192 .IP 1.
193 Inode and inode blockmap (addressing) checks:
194 bad magic number in inode,
195 bad magic numbers in inode blockmap blocks,
196 extents out of order,
197 incorrect number of records in inode blockmap blocks,
198 blocks claimed that are not in a legal data area of the filesystem,
199 blocks that are claimed by more than one inode.
200 .IP 2.
201 Inode allocation map checks:
202 bad magic number in inode map blocks,
203 inode state as indicated by map (free or in-use) inconsistent
204 with state indicated by the inode,
205 inodes referenced by the filesystem that do not appear in
206 the inode allocation map,
207 inode allocation map referencing blocks that do not appear
208 to contain inodes.
209 .IP 3.
210 Size checks:
211 number of blocks claimed by inode inconsistent with inode size,
212 directory size not block aligned,
213 inode size not consistent with inode format.
214 .IP 4.
215 Directory checks:
216 bad magic numbers in directory blocks,
217 incorrect number of entries in a directory block,
218 bad freespace information in a directory leaf block,
219 entry pointing to an unallocated (free) or out
220 of range inode,
221 overlapping entries,
222 missing or incorrect dot and dotdot entries,
223 entries out of hashvalue order,
224 incorrect internal directory pointers,
225 directory type not consistent with inode format and size.
226 .IP 5.
227 Pathname checks:
228 files or directories not referenced by a pathname starting from
229 the filesystem root,
230 illegal pathname components.
231 .IP 6.
232 Link count checks:
233 link counts that do not agree with the number of
234 directory references to the inode.
235 .IP 7.
236 Freemap checks:
237 blocks claimed free by the freemap but also claimed by an inode,
238 blocks unclaimed by any inode but not appearing in the freemap.
239 .IP 8.
240 Super Block checks:
241 total free block and/or free i-node count incorrect,
242 filesystem geometry inconsistent,
243 secondary and primary superblocks contradictory.
244 .PP
245 Orphaned files and directories (allocated, in-use but unreferenced) are
246 reconnected by placing them in the
247 .I lost+found
248 directory.
249 The name assigned is the inode number.
250 .SS Disk Errors
251 .B xfs_repair
252 aborts on most disk I/O errors. Therefore, if you are trying
253 to repair a filesystem that was damaged due to a disk drive failure,
254 steps should be taken to ensure that all blocks in the filesystem are
255 readable and writable before attempting to use
256 .B xfs_repair
257 to repair the filesystem. A possible method is using
258 .BR dd (8)
259 to copy the data onto a good disk.
260 .SS lost+found
261 The directory
262 .I lost+found
263 does not have to already exist in the filesystem being repaired.
264 If the directory does not exist, it is automatically created if required.
265 If it already exists, it will be checked for consistency and if valid
266 will be used for additional orphaned files. Invalid
267 .I lost+found
268 directories are removed and recreated. Existing files in a valid
269 .I lost+found
270 are not removed or renamed.
271 .SS Corrupted Superblocks
272 XFS has both primary and secondary superblocks.
273 .B xfs_repair
274 uses information in the primary superblock
275 to automatically find and validate the primary superblock
276 against the secondary superblocks before proceeding.
277 Should the primary be too corrupted to be useful in locating
278 the secondary superblocks, the program scans the filesystem
279 until it finds and validates some secondary superblocks.
280 At that point, it generates a primary superblock.
281 .SS Quotas
282 If quotas are in use, it is possible that
283 .B xfs_repair
284 will clear some or all of the filesystem quota information.
285 If so, the program issues a warning just before it terminates.
286 If all quota information is lost, quotas are disabled and the
287 program issues a warning to that effect.
288 .PP
289 Note that
290 .B xfs_repair
291 does not check the validity of quota limits. It is recommended
292 that you check the quota limit information manually after
293 .BR xfs_repair .
294 Also, space usage information is automatically regenerated the
295 next time the filesystem is mounted with quotas turned on, so the
296 next quota mount of the filesystem may take some time.
297 .SH DIAGNOSTICS
298 .B xfs_repair
299 issues informative messages as it proceeds
300 indicating what it has found that is abnormal or any corrective
301 action that it has taken.
302 Most of the messages are completely understandable only to those
303 who are knowledgeable about the structure of the filesystem.
304 Some of the more common messages are explained here.
305 Note that the language of the messages is slightly different if
306 .B xfs_repair
307 is run in no-modify mode because the program is not changing anything on disk.
308 No-modify mode indicates what it would do to repair the filesystem
309 if run without the no-modify flag.
310 .PP
311 .B disconnected inode
312 .IB ino ,
313 .B moving to lost+found
314 .IP
315 An inode numbered
316 .I ino
317 was not connected to the filesystem
318 directory tree and was reconnected to the
319 .I lost+found
320 directory. The inode is assigned the name of its inode number
321 .RI ( ino ).
322 If a
323 .I lost+found
324 directory does not exist, it is automatically created.
325 .PP
326 .B disconnected dir inode
327 .IB ino ,
328 .B moving to lost+found
329 .IP
330 As above only the inode is a directory inode.
331 If a directory inode is attached to
332 .IR lost+found ,
333 all of its children (if any) stay attached to the directory and therefore
334 get automatically reconnected when the directory is reconnected.
335 .PP
336 .B imap claims in-use inode
337 .I ino
338 .B is free, correcting imap
339 .IP
340 The inode allocation map thinks that inode
341 .I ino
342 is free whereas examination of the inode indicates that the
343 inode may be in use (although it may be disconnected).
344 The program updates the inode allocation map.
345 .PP
346 .B imap claims free inode
347 .I ino
348 .B is in use, correcting imap
349 .IP
350 The inode allocation map thinks that inode
351 .I ino
352 is in use whereas examination of the inode indicates that the
353 inode is not in use and therefore is free.
354 The program updates the inode allocation map.
355 .PP
356 .B resetting inode
357 .I ino
358 .B nlinks from
359 .I x
360 .B to
361 .I y
362 .IP
363 The program detected a mismatch between the
364 number of valid directory entries referencing inode
365 .I ino
366 and the number of references recorded in the inode and corrected the
367 the number in the inode.
368 .PP
369 .I fork-type
370 .B fork in ino
371 .I ino
372 .B claims used block
373 .I bno
374 .IP
375 Inode
376 .I ino
377 claims a block
378 .I bno
379 that is used (claimed) by either another inode or the filesystem
380 itself for metadata storage. The
381 .I fork-type
382 is either
383 .B data
384 or
385 .B attr
386 indicating whether the problem lies in the portion of the
387 inode that tracks regular data or the portion of the inode
388 that stores XFS attributes.
389 If the inode is a real-time (rt) inode, the message says so.
390 Any inode that claims blocks used by the filesystem is deleted.
391 If two or more inodes claim the same block, they are both deleted.
392 .PP
393 .I fork-type
394 .B fork in ino
395 .I ino
396 .B claims dup extent ...
397 .IP
398 Inode
399 .I ino
400 claims a block in an extent known to be claimed more than once.
401 The offset in the inode, start and length of the extent is given.
402 The message is slightly different
403 if the inode is a real-time (rt) inode and the extent is therefore
404 a real-time (rt) extent.
405 .PP
406 .B inode
407 .I ino
408 .B \- bad extent ...
409 .IP
410 An extent record in the blockmap of inode
411 .I ino
412 claims blocks that are out of the legal range of the filesystem.
413 The message supplies the start, end, and file offset of the extent.
414 The message is slightly different if the extent is a real-time (rt) extent.
415 .PP
416 .B bad
417 .I fork-type
418 .B fork in inode
419 .I ino
420 .IP
421 There was something structurally wrong or inconsistent with the
422 data structures that map offsets to filesystem blocks.
423 .PP
424 .B cleared inode
425 .I ino
426 .IP
427 There was something wrong with the inode that
428 was uncorrectable so the program freed the inode.
429 This usually happens because the inode claims
430 blocks that are used by something else or the inode itself
431 is badly corrupted. Typically, this message
432 is preceded by one or more messages indicating why the
433 inode needed to be cleared.
434 .PP
435 .B bad attribute fork in inode
436 .IR ino ,
437 .B clearing attr fork
438 .IP
439 There was something wrong with the portion of the inode that
440 stores XFS attributes (the attribute fork) so the program reset
441 the attribute fork.
442 As a result of this, all attributes on that inode are lost.
443 .PP
444 .B correcting nextents for inode
445 .IR ino ,
446 .B was
447 .I x
448 .B \- counted
449 .I y
450 .IP
451 The program found that the number of extents used to store
452 the data in the inode is wrong and corrected the number.
453 The message refers to nextents if the count is wrong
454 on the number of extents used to store attribute information.
455 .PP
456 .B entry
457 .I name
458 .B in dir
459 .I dir_ino
460 .B not consistent with .. value
461 .BI ( xxxx )
462 .B in dir ino
463 .IB ino ,
464 .B junking entry
465 .I name
466 .B in directory inode
467 .I dir_ino
468 .IP
469 The entry
470 .I name
471 in directory inode
472 .I dir_ino
473 references a directory inode
474 .IR ino .
475 However, the ..\& entry in directory
476 .I ino
477 does not point back to directory
478 .IR dir_ino ,
479 so the program deletes the entry
480 .I name
481 in directory inode
482 .IR dir_ino .
483 If the directory inode
484 .I ino
485 winds up becoming a disconnected inode as a result of this, it is moved to
486 .I lost+found
487 later.
488 .PP
489 .B entry
490 .I name
491 .B in dir
492 .I dir_ino
493 .B references already connected dir ino
494 .IB ino ,
495 .B junking entry
496 .I name
497 .B in directory inode
498 .I dir_ino
499 .IP
500 The entry
501 .I name
502 in directory inode
503 .I dir_ino
504 points to a directory inode
505 .I ino
506 that is known to be a child of another directory.
507 Therefore, the entry is invalid and is deleted.
508 This message refers to an entry in a small directory.
509 If this were a large directory, the last phrase would read
510 "will clear entry".
511 .PP
512 .B entry references free inode
513 .I ino
514 .B in directory
515 .IB dir_ino ,
516 .B will clear entry
517 .IP
518 An entry in directory inode
519 .I dir_ino
520 references an inode
521 .I ino
522 that is known to be free. The entry is therefore invalid and is deleted.
523 This message refers to a large directory.
524 If the directory were small, the message would read "junking entry ...".
525 .SH EXIT STATUS
526 .B xfs_repair \-n
527 (no modify mode)
528 will return a status of 1 if filesystem corruption was detected and
529 0 if no filesystem corruption was detected.
530 .B xfs_repair
531 run without the \-n option will always return a status code of 0 if
532 it completes without problems, unless the flag
533 .B -e
534 is used. If it is used, then status 4 is reported when any issue with the
535 filesystem was found, but could be fixed. If a runtime error is encountered during
536 operation, it will return a status of 1. In this case,
537 .B xfs_repair
538 should be restarted. If
539 .B xfs_repair is unable
540 to proceed due to a dirty log, it will return a status of 2. See below.
541 .SH DIRTY LOGS
542 Due to the design of the XFS log, a dirty log can only be replayed
543 by the kernel, on a machine having the same CPU architecture as the
544 machine which was writing to the log.
545 .B xfs_repair
546 cannot replay a dirty log and will exit with a status code of 2
547 when it detects a dirty log.
548 .PP
549 In this situation, the log can be replayed by mounting and immediately
550 unmounting the filesystem on the same class of machine that crashed.
551 Please make sure that the machine's hardware is reliable before
552 replaying to avoid compounding the problems.
553 .PP
554 If mounting fails, the log can be erased by running
555 .B xfs_repair
556 with the -L option.
557 All metadata updates in progress at the time of the crash will be lost,
558 which may cause significant filesystem damage.
559 This should
560 .B only
561 be used as a last resort.
562 .SH BUGS
563 The filesystem to be checked and repaired must have been
564 unmounted cleanly using normal system administration procedures
565 (the
566 .BR umount (8)
567 command or system shutdown), not as a result of a crash or system reset.
568 If the filesystem has not been unmounted cleanly, mount it and unmount
569 it cleanly before running
570 .BR xfs_repair .
571 .PP
572 .B xfs_repair
573 does not do a thorough job on XFS extended attributes.
574 The structure of the attribute fork will be consistent,
575 but only the contents of attribute forks that will fit into
576 an inode are checked.
577 This limitation will be fixed in the future.
578 .PP
579 The no-modify mode
580 .RB ( \-n
581 option) is not completely accurate.
582 It does not catch inconsistencies in the freespace and inode
583 maps, particularly lost blocks or subtly corrupted maps (trees).
584 .PP
585 The no-modify mode can generate repeated warnings about
586 the same problems because it cannot fix the problems as they
587 are encountered.
588 .PP
589 If a filesystem fails to be repaired, a metadump image can be generated
590 with
591 .BR xfs_metadump (8)
592 and be sent to an XFS maintainer to be analysed and
593 .B xfs_repair
594 fixed and/or improved.
595 .SH SEE ALSO
596 .BR dd (1),
597 .BR mkfs.xfs (8),
598 .BR umount (8),
599 .BR xfs_admin (8),
600 .BR xfs_metadump (8),
601 .BR xfs (5).